This repository is part of IPAL - an Industrial Protocol Abstraction Layer. IPAL aims to establish an abstract representation of industrial network traffic for subsequent unified and protocol-independent industrial intrusion detection. IPAL consists of a transcriber to automatically translate industrial traffic into the IPAL representation, an IDS Framework implementing various industrial intrusion detection systems (IIDSs), and a collection of evaluation datasets. For details about IPAL, please refer to our publications listed down below.

The ever-increasing digitization in industries enables the automatization of complex physical processes and, with progressive integration into the Internet, also large-scale distributed systems. Due to both trends, well-known cyber-security problems are inherited, which, in the past, already led to severe attacks, e.g., the striking of the Ukrainian power grid in 2015. Supplementing proactive measures, Industrial Intrusion Detection Systems (IIDSs) promise to detect such attacks timely by monitoring the communication between automatization devices or accessing the processes’ physical state. Researchers proposed many IIDS solutions until today. However, due to a lack of standard interfaces and diverse communication protocols across industrial domains, great efforts are required to adapt existing IIDSs to new domains and communication protocols. To overcome this issue, we propose IPAL - a common message format that decouples IIDSs from domain-specific communication protocols. This representation applies to most IIDSs, as all their input data requirements are covered. Moreover, the required data is extractable across multiple industrial protocols due to inherent similarities in their communication patterns.

This repository contains the ipal-iids framework together with implementations of several IIDSs based on the IPAL message and state format generated by our second project the ipal-transcriber. As shown in the overview figure below, the IIDS framework consists of two phases. In the training phase, the IIDSs learn an internal model based on a training dataset and a configuration file with IIDS specific parameters. During the live phase, the IIDSs load the trained models and search for anomalies in live data.

The IIDS framework contains implementations of the following IIDSs. Note that we distinguish between IIDSs operating on the IPAL message format (on a per-network packet basis) or on the IPAL state format (a summary of all industrial process values for a given point in time).

Note: IDSs marked with * are not available publically, but can be obtained on request.

• Konrad Wolsing, Eric Wagner, Antoine Saillard, and Martin Henze. 2022. IPAL: Breaking up Silos of Protocol-dependent and Domain-specific Industrial Intrusion Detection Systems. In 25th International Symposium on Research in Attacks, Intrusions and Defenses (RAID 2022), October 26–28, 2022, Limassol, Cyprus. ACM, New York, NY, USA, 17 pages. https://doi.org/10.1145/3545948.3545968
• Wolsing, Konrad, Eric Wagner, and Martin Henze. "Poster: Facilitating Protocol-independent Industrial Intrusion Detection Systems." Proceedings of the 2020 ACM SIGSAC Conference on Computer and Communications Security. 2020 https://doi.org/10.1145/3372297.3420019

If you are new to IPAL and want to learn about the general idea or try out our tutorials, please refer to IPAL's main repository: https://github.com/fkie-cad/ipal.

• ipal-iids requires libgsl (or libgsl-dev) to be installed. See https://www.gnu.org/software/gsl/doc/html/index.html for further information.
• The Autoregression IIDS requires ar. Please make sure that python-dev or the corresponding version (e.g. python3.9-dev) is installed on your system

Use python3 -m pip install . to install the scripts and dependencies system-wide using the pip python package installer. This will install dependencies and the iids modules to the local site packages and add the ipal-iids, ipal-visualize-model and ipal-extend-alarms scripts to the PATH. The scripts can then be invoked system-wide (e.g. ipal-iids -h).

Alternatively, the project's dependencies can be installed locally in a virtual environment using the misc/install.sh script or manually with:

python3 -m venv venv
source venv/bin/activate

python3 -m pip install numpy
python3 -m pip install -r requirements.txt

The scripts can then be invoked after activating the virtual environment from the root of the project repository, e.g.:

source venv/bin/activate
./ipal-evaluate -h
deactivate

Use docker build -t ipal-ids-framework:latest . to build a Docker image with a pip installation of the project and development dependencies. The scripts can then be used within containers using the built image, e.g.:

docker run -it ipal-ids-framework:latest /bin/bash
ipal-ids -h

The ipal-iids consists of two phases. During training, the parameters --train.ipal or --train.state have to be provided together with a configuration file via --config. Afterwards, the live detection phase starts. Therefore, the parameters --live.ipal or --live.state have to be provided and --output defines the location where the annotated IIDS output is written to.

Each IIDS has its own options which can be retrieved by ipal-iids --default.config [ids-name].

usage: ipal-iids [-h] [--train.ipal FILE] [--train.state FILE] [--train.combiner FILE] [--live.ipal FILE] [--live.state FILE] [--output FILE] [--config FILE] [--combiner.config FILE] [--default.config IDS]
                 [--combiner.default.config Combiner] [--retrain] [--log STR] [--logfile FILE] [--compresslevel INT] [--version]

This program contains the ipal-iids framework together with implementations of several IIDSs based on the IPAL message and state format.

options:
  -h, --help            show this help message and exit
  --train.ipal FILE     input file of IPAL messages to train the IDS on ('-' stdin, '*.gz' compressed).
  --train.state FILE    input file of IPAL state messages to train the IDS on ('-' stdin, '*.gz' compressed).
  --train.combiner FILE
                        input file of IPAL or state messages to train the combiner on ('-' stdin, '*.gz' compressed).
  --live.ipal FILE      input file of IPAL messages to perform the live detection on ('-' stdin, '*.gz' compressed).
  --live.state FILE     input file of IPAL state messages to perform the live detection on ('-' stdin, '*.gz' compressed).
  --output FILE         output file to write the anotated IDS output to (Default:none, '-' stdout, '*,gz' compress).
  --config FILE         load IDS configuration and parameters from the specified file ('*.gz' compressed).
  --combiner.config FILE
                        load Combiner configuration and parameters from the specified file ('*.gz' compressed).
  --default.config IDS  dump the default configuration for the specified IDS to stdout and exit, can be used as a basis for writing IDS config files. Available IIDSs are:
                        Autoregression,BLSTM,DecimalPlaces,DecisionTree,DTMC,Dummy,Exists,ExtraTrees,Histogram,inter-arrival-mean,inter-arrival-
                        range,InvariantRules,IsolationForest,MinMax,NaiveBayes,Optimal,PASAD,RandomForest,SVM,Seq2SeqNN,Steadytime,TABOR
  --combiner.default.config Combiner
                        dump the default configuration for the specified Combiner to stdout and exit, can be used as a basis for writing Combiner config files. Available Combiners are:
                        Any,Matrix,Gurobi,Heuristic,LogisticRegression,SVM,LSTM
  --retrain             retrain regardless of a trained model file being present.
  --log STR             define logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL) (Default: WARNING).
  --logfile FILE        file to log to (Default: stderr).
  --compresslevel INT   set the gzip compress level. 0 no compress, 1 fast/large, ..., 9 slow/tiny. (Default: 9)
  --version             show program's version number and exit

The configuration file determines the parameters for each IIDS. A default configuration for each IIDS can be obtained with ipal-iids --default.config [IIDS name]:

ipal-iids --default.config inter-arrival-mean
{
    "inter-arrival-mean": {
        "_type": "inter-arrival-mean",
        "model-file": "./model",
        "N": 4,
        "W": 5
    }
}

The IIDS framework allows for using multiple IIDSs in parallel. Each entry in the configuration file can have a different name, e.g., one IIDS for each sensor of a physical system. Currently, the output of multiple IIDSs is combined with 'or' - meaning an alert is emitted if at least one IIDS detected an anomaly.

If multiple IIDSs are used in parallel, it is possible to specify a combiner that fuses the results of the individual approaches into a unified alert. Therefore, different strategies can be used as listed in the following table:

To utilize a combiner, the IIDS framework requires a dedicated configuration file. A default configuration for each combiner can be obtained with ipal-iids --combiner.default.config [Combiner name]:

ipal-iids --combiner.default.config Matrix
{
    "_type": "Matrix",
    "model-file": null,
    "matrix": [],
    "threshold": 0,
    "use_scores": false,
    "keys": [],
    "lookahead": 0
}

This configuration file must be provided in addition to the regular IIDS configuration file. An exemplary command would be:

ipal-iids \
  --config [IDS config file] --train.state [IDS training file] \
  --combiner.config [combiner config file] --train.combiner [Combiner training file] \
  --live.state [live file] --output [output file]

Note that some combiners require dedicated training files. It is recommended to use a separate training file for the combiner.

The preprocessors are useful for IIDSs, that require a certain input format. E.g., some machine-learning IIDSs work best if their data is scaled between 0 and 1. Only IIDSs inheriting from the FeatureIDS can use the preprocessors. Initially, the preprocessors are fitted to the training data. Currently, the following preprocessors are implemented:

Multiple preprocessors can be used in series. The following example shows how preprocessors are defined in the configuration file:

{
    "SVM Preprocessor Example" : {
        "_type": "SVM",
        ...
        "features" : ["src", "type", "state;4:PID Setpoint", "length"],
        "preprocessors": [
            {"method" : "Mean", "features" : ["state;4:PID Setpoint", "length"]},
            {"method" : "Categorical", "features" : ["type"]}
        ],
        ...
    }
}

This tool allows for visualizing the trained models for an IIDS configuration. To plot a specific model use ipal-visualize-model [path-to-config-file].

ipal-visualize-model  -h
usage: ipal-visualize-model [-h] [--log STR] [--logfile FILE] [--version] FILE

positional arguments:
  FILE            load the IDS configuration of the trained model ('*.gz' compressed).

options:
  -h, --help      show this help message and exit
  --log STR       define logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL). Default is WARNING.
  --logfile FILE  File to log to. Default is stderr.
  --version       show program's version number and exit

The ipal-iids tool works as an online tool - meaning IIDSs have to decide whether they emit an alert live. Therefore, alerts can not be emitted retroactively, which is sometimes needed for evaluation. As few IIDSs possibly need to retroactively emit alerts, the ipal-extend-alarms script post-processes the IIDS output afterward. IIDSs with the support for ipal-extend-alarms need the parameter adjust: true to be set in their configuration files.

./ipal-extend-alarms -h
usage: ipal-extend-alarms [-h] [--log STR] [--logfile FILE] [--version] FILE [FILE ...]

positional arguments:
  FILE            files to extend alarms ('*.gz' compressed).

options:
  -h, --help      show this help message and exit
  --log STR       define logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL). Default is WARNING.
  --logfile FILE  File to log to. Default is stderr.
  --version       show program's version number and exit

Note that the ipal-extend-alarms tool does not implement combiners and simply combines the results with OR.

The set of tools used for development, code formatting, style checking, and testing can be installed with the following command:

python3 -m pip install -r requirements-dev.txt

All tools can be executed manually with the following commands and report errors if encountered:

black .
flake8
python3 -m pytest

A black and flake8 check of modified files before any commit can also be forced using Git's pre-commit hook functionality:

pre-commit install

More information on the black and flake8 setup can be found at https://ljvmiranda921.github.io/notebook/2018/06/21/precommits-using-black-and-flake8/

Currently there are two ways how support for a new IIDS can be added.

At first you can create a new IIDS and make it part of the IPAL code:

1. Add a new folder and IIDS module in ids/[ids name]/[ids name].py
2. Create a new IIDS class inheriting the MetaIDS class (see ids/ids.py) or inheriting the FeatureIDS class (see ipal_iids/ids/featureids.py) for preprocessor support. The IIDS class may implement:
   • train: given some training data, the IIDS should learn its internal model
   • new_ipal_msg: given a new IPAL message, return whether the IIDS detected an anomaly
   • new_state_msg: given a new IPAL state message, return whether the IIDS detected an anomaly
   • save_trained_model: save the trained model to disc
   • load_trained_model: load a trained model from disc
   • visualize_model: create a Matplotlib visualization of the model for debugging purposes
3. Add the new IIDS to the list in ids/utils.py
4. Add the new IIDS to the list in tests/conftest.py
5. Add the new IIDS to the implemented IIDSs table above

Note: The name of an IIDS may not begin with "_"!

Secondly you can create a config file specifying from which file the IIDS should be loaded:

1. Create a so called "extra" config file specifying the names and locations of the new IIDSs (or combiners and preprocessors). Paths are either absolute or relativ to the position of the config file. The config file is passed to IPAL via the --extra.config argument. An example config file could look like this:

{
    "IDS": [
        {
            "name": "TestIDS",
            "path": "./testids.py"
        }
    ],

    "Combiner": [
        {
            "name": "Test",
            "path": "./testcombiner.py"
        }
    ],

    "Preprocessor": [
        {
            "name": "Test",
            "path": "./testpreprocessor.py"
        }
    ]
}

Note: The names of the IIDSs should be equal to the names of the corresponding Python classes. The names of the combiners should be equal to the class names without the suffix "Combiner", e.g. your combiner class is called "AwesomeCombiner" then you should write "Awesome" as the name for your combiner into your "extra" config file.

The process for adding a new state extraction method is the following:

1. Add a new preprocessor module in preprocessors/
2. Create a new preprocessor class inheriting the Preprocessor class (see preprocessors/preprocessor.py). The preprocessor class may implement:
   • fit: given a set of training data, train the preprocessor on it
   • transform: preprocess a given data sample based on the fitted model
   • reset: reset the preprocessor between individual dataset
   • get_fitted_model: return a representation of the fitted mode, which can be saved to disc
   • from_fitted_model: return an initialized preprocessor based on a previously saved model
3. Add the new preprocessor to the list in preprocessors/utils.py
4. Add the new preprocessor to the preprocessor list table above

Adding a combiner is analog to adding a new preprocessor.

• Antoine Saillard (RWTH Aachen University & Fraunhofer FKIE)
• David Valero Ribes (RWTH Aachen University)
• Dominik Kus (RWTH Aachen University)
• Eric Wagner (Fraunhofer FKIE & RWTH Aachen University)
• Frederik Basels (RWTH Aachen University)
• Jonas Lohmann (RWTH Aachen University)
• Konrad Wolsing (Fraunhofer FKIE & RWTH Aachen University)
• Lea Thiemt (RWTH Aachen University)
• Sven Zemanek (Fraunhofer FKIE)

MIT License. See LICENSE for details.