# 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 (see MAL Simulator) or analysis.
MAL Toolbox also gives the ability to view the AttackGraph/Model graphically in neo4j.
[Documentation](https://mal-lang.org/mal-toolbox/index.html)(Work in progress)
## 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
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 associations that make it up.
Assets and associations are objects of classes created using the language
classes factory submodule in runtime. It also allows for `Attacker` objects
to be created and associated with attack steps on assets in the model.
The most relevant methods of the Model 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 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.
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.
# Usage
## Installation
```
pip install mal-toolbox
```
## 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.
## 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.
## Code examples / Tutorial
To find code examples and tutorials, visit the
[MAL Toolbox Tutorial](https://github.com/mal-lang/mal-toolbox-tutorial/tree/main) repository.
# Tests
There are unit tests inside of ./tests.
Before running the tests, make sure to install the requirements in ./tests/requirements.txt with `python -m pip install -r ./tests/requirements.txt`.
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>`.
Raw data
{
"_id": null,
"home_page": null,
"name": "mal-toolbox",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "mal",
"author": null,
"author_email": "Andrei Buhaiu <buhaiu@kth.se>, Giuseppe Nebbione <nebbione@kth.se>, Nikolaos Kakouros <nkak@kth.se>, Jakob Nyberg <jaknyb@kth.se>, Joakim Loxdal <loxdal@kth.se>",
"download_url": "https://files.pythonhosted.org/packages/7e/70/d639bb54654073d31ece9838cbc69df56976a1f965e62acfe5ae7c729194/mal_toolbox-0.1.11.tar.gz",
"platform": null,
"description": "# MAL Toolbox overview\n\nMAL Toolbox is a collection of python modules to help developers create and work with\nMAL ([Meta Attack Language](https://mal-lang.org/)) models and attack graphs.\n\nAttack graphs can be used to run simulations (see MAL Simulator) or analysis.\nMAL Toolbox also gives the ability to view the AttackGraph/Model graphically in neo4j.\n\n[Documentation](https://mal-lang.org/mal-toolbox/index.html)(Work in progress)\n\n## The Language Module\n\nThe language module provides various tools to process MAL languages.\n\n### The Language Specification Submodule\n\nThe language specification submodule provides functions to load the\nspecification from a .mar archive(`load_language_specification_from_mar`) or a\nJSON file(`load_language_specification_from_json`). This specification will\nthen be used to generate python classes representing the assets and\nassociations of the language and to determine the attack steps for each asset\nwhen generating the attack graph.\n\n### The Language Classes Factory Submodule\n\nThe language classes factory submodule is used to generate python classes\nusing the `python_jsonschema_objects` package from a language specification.\nThe classes generated by the `create_classes` function can then be accessed\nfrom within that namespace(.e.g: `lang_classes_factory.ns.Application()`,\n`lang_classes_factory.ns.AppExecution()`). Because these classes are built\nusing JSON Schema validators they will enforce their restrictions when using\nthe python objects created. These classes are typically used in conjunction\nwith model module to create instance models.\n\n## The Model Module\n\nWith a MAL language a Model (a MAL instance model) can be created either\nfrom a model file or empty.\n\nThe model class will store all of the relevant information to the MAL\ninstance model, most importantly the assets and associations that make it up.\n\nAssets and associations are objects of classes created using the language\nclasses factory submodule in runtime. It also allows for `Attacker` objects\nto be created and associated with attack steps on assets in the model.\nThe most relevant methods of the Model are the ones used to add different\nelements to the model, `add_asset`, `add_association`, and `add_attacker`.\n\nModel objects can be used to generate attack graphs with the AttackGraph module.\n\n## The Attack Graph Module\n\nThe attack graph module contains tools used to generate attack graphs from\nexisting MAL instance models and analyse MAL attack graphs. The function used\nto generate the attack graph is `generate_graph` and it requires the instance\nmodel and language specification. The resulting attack graph will contain\nnodes for each of the attack steps. The structure of the attack node data\nclass can be seen in `attackgraph/node.py` file. Of note are the lists of\nchildren and parents which allow for easy reference to the other attack step\nnodes related and the asset field which will contain the object in the model\ninstance to which this attack step belongs to, if this information is\navailable.\n\nIf it is relevant the `attach_attackers` function can be called on the\nresulting attack graph with the instance model given as a parameter in order\nto create attack step nodes that represent the entry points of the attackers\nand attach them to the attack steps specified in the instance model.\n\n## Ingestors Module\n\nThe ingestors module contains various tools that can make use of the instance\nmodel or attack graph. Currently the Neo4J ingestor is the only one available\nand it can be used to visualise the instance model and the attack graph.\n\n\n# Usage\n\n## Installation\n\n```\npip install mal-toolbox\n```\n\n## Configuration\nA default configuration file `default.conf` can be found in the package\ndirectory. This contains the default values to use for logging and can also be\nused to store the information needed to access the local Neo4J instance.\n\n## Command Line Client\nIn addition to the modules that make up the MAL-Toolbox package it also\nprovides a simple command line client that can be used to easily generate\nattack graphs from a .mar language specification file and a JSON instance\nmodel file.\n\nThe usage is: `maltoolbox gen_ag [--neo4j] <model_json_file>\n<language_mar_file>`\n\nIf the `--neo4j` flag is specified the model and attack graph will be loaded\ninto a local Neo4J instance.\n\n## Code examples / Tutorial\n\nTo find code examples and tutorials, visit the\n[MAL Toolbox Tutorial](https://github.com/mal-lang/mal-toolbox-tutorial/tree/main) repository.\n\n# Tests\nThere are unit tests inside of ./tests.\nBefore running the tests, make sure to install the requirements in ./tests/requirements.txt with `python -m pip install -r ./tests/requirements.txt`.\n\nTo 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>`.\n",
"bugtrack_url": null,
"license": "Apache Software License",
"summary": "A collection of tools used to create MAL models and attack graphs.",
"version": "0.1.11",
"project_urls": {
"Bug Tracker": "https://github.com/mal-lang/mal-toolbox/issues",
"Homepage": "https://github.com/mal-lang/mal-toolbox",
"Repository": "https://github.com/mal-lang/mal-toolbox"
},
"split_keywords": [
"mal"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1feedbcb78f55929d1f3833159a0495815efd9a71dd0809a21265e773e77a501",
"md5": "d40e3db438799dc7b6061165530ee570",
"sha256": "34dfab8f72a10c847f35b6ff3710f9c84c349ce9267fa522bdeab7d05bdc97b9"
},
"downloads": -1,
"filename": "mal_toolbox-0.1.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d40e3db438799dc7b6061165530ee570",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 67720,
"upload_time": "2024-11-25T12:22:57",
"upload_time_iso_8601": "2024-11-25T12:22:57.633379Z",
"url": "https://files.pythonhosted.org/packages/1f/ee/dbcb78f55929d1f3833159a0495815efd9a71dd0809a21265e773e77a501/mal_toolbox-0.1.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7e70d639bb54654073d31ece9838cbc69df56976a1f965e62acfe5ae7c729194",
"md5": "27ea071bb90e235c01a2767cfb9a357a",
"sha256": "be2fd93c97527255bfe61838c49acdb18cf5428b3afa18987c03e65ad59a42f0"
},
"downloads": -1,
"filename": "mal_toolbox-0.1.11.tar.gz",
"has_sig": false,
"md5_digest": "27ea071bb90e235c01a2767cfb9a357a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 64004,
"upload_time": "2024-11-25T12:23:01",
"upload_time_iso_8601": "2024-11-25T12:23:01.191809Z",
"url": "https://files.pythonhosted.org/packages/7e/70/d639bb54654073d31ece9838cbc69df56976a1f965e62acfe5ae7c729194/mal_toolbox-0.1.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-25 12:23:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mal-lang",
"github_project": "mal-toolbox",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "docopt",
"specs": []
},
{
"name": "PyYAML",
"specs": []
},
{
"name": "python-jsonschema-objects",
"specs": []
},
{
"name": "py2neo",
"specs": []
},
{
"name": "antlr4-tools",
"specs": []
},
{
"name": "antlr4-python3-runtime",
"specs": []
},
{
"name": "mypy",
"specs": []
},
{
"name": "types-docopt",
"specs": []
},
{
"name": "types-PyYAML",
"specs": []
}
],
"lcname": "mal-toolbox"
}
JSON
