NAV
shell

Get Started

The Exein CLI is a simple tool that helps you to secure your IoT device using Exein cutting-edge technology. Exein CLI has been designed to ease secure firmware development. This tutorial guides you step-by-step to perform the operations required to build and install a secured firmware using Exein CLI. In order to secure your device the following steps are necessary:

  1. Create an Exein Project
  2. Create an Audit Build
  3. Tag the executable and collect data
  4. Create Release Build
  5. Secure your process

Prerequisites

./exein-installer-current.run

Make sure you have downloaded and installed the Exein CLI. If you haven’t done so already, please download the CLI at https://beta.exein.io/static/exein-installer-current.run and install it by running in your terminal:

Make sure you have also registered an account with Exein. If you haven’t done so already, please visit https://hub.exein.io/signup to register your account.

Make sure you have cmake 3.16 or later installed in your working environment.

Before proceeding with the installation of Exein inside your firmware, please note the latest version of Exein only supports the Linux Kernel Versions:

and the following architectures:

Support for more kernel versions and architectures is coming soon.

Please also note that the latest version of Exein only supports the following build systems:

Support for Yocto is on the way.

Only glibc is supported.

Step 1: Create an Exein Project

exein init --name "my-first-project" --type "buildroot"

In order to initialize an Exein project, navigate to the main directory where your firmware build resides and run:

The exein init command will first ask you to authenticate to Exein using your registered credentials. If authentication is successful, a file named “.exein” will be created in the firmware project directory. This file stores your Exein CLI project configurations.

Step 2: Create an Audit Build

exein build audit

After having successfully initialized an Exein project in your firmware main directory, the next step is to create an audit build for your firmware by running the exein build audit CLI command:

Exein secures the device through the Exein Machine Learning Engine (MLE). In order to detect suspicious activities, the MLE needs to first learn the regular firmware behaviour: the audit build consists of the original firmware build with the addition of the Exein components that are responsible for collecting the data needed to train the MLE.

Build directories are created in ~/.local/share/exein-cli/.

Step 3: Tag the target executable and collect data

After having built the audit version of your firmware, you need to flash the it on your target device -or on a virtual machine, depending on your need - and collect the behavioral data required to train the MLE security model for your firmware.

This step can be broken down in two main parts:

  1. Tagging the target executable
    To identify the target processes, you need to add a 16-bit integer TAG to your executable. Exein will use this TAG number to monitor the activity of this process.

  2. Running the process data collection
    Exein needs to collect data about the regular firmware behaviour to train the MLE. During this phase, you should test all the functionalities you expect to be used in your target application so that the MLE will be able to recognize them in the future and not flag them as anomalies.

The main goal of this step is to have Exein automatically produce a dataset file containing all the process regular behavior that has been observed and recorded during the firmware test operations. This file will be used to train the Machine Learning Engine security model for your firmware and to create the final release build.

For more details on tagging your target executable and on processes data collection, see below.

Step 3a. Tag the target executable

To tag an executable, add a section to the ELF executable file. The TAG is a user-defined 16-bits integer: use its little-endian 2-byte hexadecimal representation (e.g., for TAG number 13330, its HEX representation is 3412, add bytes 12 and 34).

Example

echo -ne "\x33\x33" > exein
objcopy --add-section .exein=exein --set-section-flags .exein=noload,readonly /usr/sbin/uhttpd
rm exein

Example: in this example uhttpd is tagged using TAG number 13107 (HEX = 3333) by adding the following lines to the install section of uhttpd Makefile.

Step 3b. Run the process data collection

To start data collection of a tagged running process:

training-forwarder IP PORT TAG SECURE_SEED PKT_SIZE
exein receive --port PORT --tag TAG

During this phase, it is extremely important to test all the functionalities you expect to be used in your target application when deployed. This will allow Exein to create a strong model of your target expected behavior and effectively detect anomalous deviations from it. Once you have completed the firmware tests, stop the receiver using CTRL-C.

Example

echo 1 > /proc/exein/mode_ctl
training-forwarder 192.168.1.10 13107 13107 35465436 1350

To forward the training data of the process with TAG: 13107 to the server listening at UDP:192.168.1.10:13107 with the kernel SECURE_SEED 35465436, do the following (use 1350 as default packet size):

dmesg |grep "ExeinLSM - lsm is active"
[0.001962] ExeinLSM - lsm is active: seed [1841749789]

Root users can retrieve the kernel SECURE_SEED using the following command:

On the CLI, run exein receive and check the number of received hooks. Test all the functionalities of the tagged executable (e.g. web-page serving) and stop the receiver when all the tests are completed. For robust results, the number of received hooks should be at least 15K.

Step 4: Create Release Build

After having collected the training data for the MLE, the next step is to actually train the MLE using this data and to create the release build with Exein. This can be done in two ways: either automatically or manually.

Step 4a: Automatic Release Build

exein train --file "path/to/training-data" --build

Training the MLE and creating the release firmware build can be done automatically running only one CLI command:

exein receive --port 13107 --tag 13107
Received hooks: <numhooks>

With the “build” option activated, exein train handles autonomously the MLE training in the background. In fact, when the command is launched, the CLI enters a waiting phase and checks the training server at regular intervals. When model training is completed, the CLI exits the waiting phase, downloads the trained MLE model and creates a build of your firmware with Exein in release mode inside, ready to be deployed.

Step 4b: Manual Release Build

exein train --file "path/to/training-data"

Alternatively, you can train the MLE and then later independently create the release build. To train the MLE model run:

In this case, the CLI skips the waiting phase, returns a positive output and ends the program as soon as the training request has been taken over by Exein servers.

exein status

At this point, you can manually check the model training status using the command:

This command shows inside a table the status for all the MLE models associated to the Exein project you are working on. Each model is identified by a unique model ID. Last trained models in order of time are shown at the end of the table. An estimated time of completion is calculated. Also the status and the model score are reported as soon as they are available.

exein build release --id "unique_model_id"

After having ensured that your model has been correctly trained - with its status is marked as COMPLETED and a positive score - launch the exein build release command and specify which MLE model to use to create the final release build:

As for the automatic release build option, the result of the manual release build procedure is a new folder where you can find the completed firmware build with Exein inside ready for deployment.

Step 5: Secure your process

mle-player SECURE_SEED MODEL_CONFIG_PATH TF-LITE_MODEL_PATH

Finally, to secure your process using the MLE-Player, tag the target executable (as done in Step 3a), flash the release build on your target device and run the mle-player command providing the .ini configuration file and the trained .tflite MLE model. By default, the config file and the MLE model are stored in /etc/exein/.

Example

mle-player 1841749789 ARMEL-F-414162-config-13107.ini ARMEL-F-414162-model-13107.tflite &>/dev/null &
dmesg |grep "ExeinLSM - lsm is active"
[0.001962] ExeinLSM - lsm is active: seed [1841749789]

where the first argument is the kernel SECURE_SEED, the second argument is the path of the model config file, and the third argument is the .tflite model. Root users can retrieve the kernel SECURE_SEED using the following command:

At this point, Exein is active and monitoring the behavior of your target process: as soon as anomalies are detected, the MLE-Player reacts and takes action against the anomalous processes, securing your device from potential threats.

CLI Reference

exein [command] [arguments]

Commands on Exein CLI are issued in the following way:

exein init

Description

Initialize a new Exein project.

Usage

exein init TYPE NAME DESCRIPTION

Arguments

Argument Description
type build system used for the project (only Buildroot is supported as of the 0.01 release, with Yocto and OpenWRT in the pipeline for the 0.02 release)
name project name specified by the user
description (optional) a short description of the project

Extended Description

exein init is the first command used when a new Exein project is initialized. A login prompt shows up if the user is not logged in with username and password. A file named “.exein” is then created in the firmware project directory. This file stores the Exein CLI project configurations.

Example

$ exein init --type buildroot --name exein-ip-cam



                       .__
    ____ ___  ___ ____ |__| ____
  _/ __ \\  \/  // __ \|  |/    \
  \  ___/ >    <\  ___/|  |   |  \
   \___  >__/\_ \\___  >__|___|  /
       \/      \/    \/        \/  Installer v0.3



Email: giovanni@exein.io
Password:
[2021-01-13T09:34:45Z INFO ] Logged in as: giovanni@exein.io
[2021-01-13T09:34:47Z INFO ] Exein repository initialized

This example initializes a new Exein project named “exein-ip-cam” with buildroot as target build system inside the current working directory.

exein build

Description

Create a firmware build with Exein inside.

Usage

exein build COMMAND

exein build audit

Description

Create a firmware build with Exein in auditing mode.

Usage

exein build audit

Arguments

This command takes no arguments.

Extended Description

When exein build audit is launched by the user, the Exein CLI first checks that the current directory contains an “.exein” project. Then it copies the firmware source into a storage folder and runs a first build to check if the firmware compiles without Exein inside. If the compilation is successful, it adds Exein (kernel patch and MLE software) to the project and runs the "make" command for Buildroot. The terminal shows the same output that you would have during a normal build. At the end of the build, a message showing the directory where to find the build with Exein is displayed to the user.

Example

$ exein build audit

            .__
    ____ ___  ___ ____ |__| ____
  _/ __ \\  \/  // __ \|  |/    \
  \  ___/ >    <\  ___/|  |   |  \
   \___  >__/\_ \\___  >__|___|  /
       \/      \/    \/        \/  Installer v0.3



[2021-01-13T09:35:02Z INFO ] Logged in as: giovanni@exein.io
mkdir -p /home/giovanni/.local/share/exein-cli/7d98e4a2-3653-47d9-9843-26f2ac19b998/output/build/buildroot-config/lxdialog
PKG_CONFIG_PATH="" make CC="/usr/bin/gcc" HOSTCC="/usr/bin/gcc" \
    obj=/home/giovanni/.local/share/exein-cli/7d98e4a2-3653-47d9-9843-26f2ac19b998/output/build/buildroot-config -C support/kconfig -f Makefile.br conf
make[1]: Entering directory '/home/giovanni/.local/share/exein-cli/7d98e4a2-3653-47d9-9843-26f2ac19b998/support/kconfig'

This example builds the firmware hosted in the current project with Exein in auditing mode inside.

exein receive

Description

Receives data from tagged executable processes. Data are sent by running training-forwarder on the device. This command creates the dataset file required to train the MLE.

Usage

exein receive --port PORT --tag TAG

Arguments

Argument Description
port port used by training-forwarder to send data
tag tag number used to tag the target executable

Extended Description

The command exein receive starts a UDP server listening on the specified port to receive data from a tagged executable process . Data are sent by running training-forwarder on the device using the same port. This command creates the dataset file required to train the MLE. Use the same tag number that have been assigned to the target process during the tagging operation and the same port used by the command training-forwarder. During this phase, it is recommended to test all the functionalities you expect to be used in your target application. Once you have completed the tests, stop the receiver using CTRL-C.

Example

$ exein receive --port 13107 --tag 13107

                       .__
    ____ ___  ___ ____ |__| ____
  _/ __ \\  \/  // __ \|  |/    \
  \  ___/ >    <\  ___/|  |   |  \
   \___  >__/\_ \\___  >__|___|  /
       \/      \/    \/        \/  Installer v0.3



[2021-01-13T09:55:21Z INFO ] Receiving...

This example shows how to receive data on port 13107 for the tagged process 13017.

$ echo 1 > /proc/exein/mode_ctl
$ ./training-forwarder 192.168.1.10 13107 13107 35465436 1350

On the device, to forward the training data of the target process tagged with 13107 to the server listening to UDP:192.168.1.10:13107 using kernel seed 35465436 run the following command (use 1350 as default packet size):

$ dmesg |grep "ExeinLSM - lsm is active"
[0.001962] ExeinLSM - lsm is active: seed [1841749789]

Root users can retrieve the kernel seed using the following command:

exein build release

Description

Create a firmware build with Exein in release mode.

Usage

exein build release ID

Arguments

Argument Description
id unique ID of the Exein MLE model to be used for creating the release build

Extended Description

When exein build release is launched by the user, the Exein CLI checks that there is an active “.exein” project in the current directory. It then checks that the MLE model specified in “id” is in the COMPLETED state. Much in the same way as with the exein build audit command, a folder containing a copy of the firmware source, the Exein software and the trained MLE model is created and a build is started. On the terminal the build process runs as usual, displaying the relevant output messages.

Example

exein build release --id 8b8bd444-6da1-4406-9781-4f4d58347d13



                       .__
    ____ ___  ___ ____ |__| ____
  _/ __ \\  \/  // __ \|  |/    \
  \  ___/ >    <\  ___/|  |   |  \
   \___  >__/\_ \\___  >__|___|  /
       \/      \/    \/        \/  Installer v0.3



[2021-01-13T09:52:33Z INFO ] Logged in as: giovanni@exein.io
mkdir -p /home/giovanni/.local/share/exein-cli/761804b1-0028-4d84-8f58-d739fe26a144/output/build/buildroot-config/lxdialog
PKG_CONFIG_PATH="" make CC="/usr/bin/gcc" HOSTCC="/usr/bin/gcc" \
    obj=/home/giovanni/.local/share/exein-cli/761804b1-0028-4d84-8f58-d739fe26a144/output/build/buildroot-config -C support/kconfig -f Makefile.br conf
make[1]: Entering directory '/home/giovanni/.local/share/exein-cli/761804b1-0028-4d84-8f58-d739fe26a144/support/kconfig'
/usr/bin/gcc -D_DEFAULT_SOURCE -D_XOPEN_SOURCE=600  -DCURSES_LOC="<ncurses.h>" -DNCU

This example builds the firmware hosted in the current project with Exein in release mode inside. The trained security model with unique ID: "8b8bd444-6da1-4406-9781-4f4d58347d13" is used as the Machine Learning Engine for the firmware.

exein train

Description

Train an Exein MLE model.

Usage

exein train BUILD FILE

Arguments

Argument Description
build this argument takes no additional parameters but rather it indicates the intention of automatically training an Exein MLE model and creating a final “release” build of the firmware ready for deploy without ever leaving the current terminal window
file path to the training data file

Extended Description

When exein train is launched by the user, the Exein CLI checks that there is an active “.exein” project in the current directory. It then sends the training data file to Exein’s server along with a reference to the firmware. If the "build" option has not been selected, it ends immediately after sending the file and it is up to the user to continue with the build once the training is complete.

If the "build" option has been selected, an active wait starts and every 15 seconds the model training status is checked by the CLI. As soon as the training phase is completed, a folder containing a copy of the firmware source, the Exein software and the trained MLE model is created and a build is started (much in the same way as with the exein build release command). On the terminal the build process runs as usual, displaying the relevant output messages.

Example

$ exein train --file training-dataset.csv.zip



                       .__
    ____ ___  ___ ____ |__| ____
  _/ __ \\  \/  // __ \|  |/    \
  \  ___/ >    <\  ___/|  |   |  \
   \___  >__/\_ \\___  >__|___|  /
       \/      \/    \/        \/  Installer v0.3



[2021-01-13T09:37:17Z INFO ] Logged in as: giovanni@exein.io
[2021-01-13T09:37:22Z INFO ] Training data uploaded successfull. Model id: 8b8bd444-6da1-4406-9781-4f4d58347d13

This example trains a security model using the training dataset found at "training-dataset.csv.zip".

exein status

Description

Check the status of the current Exein project model training.

Usage

exein status

Arguments

This command takes no argument.

Extended Description

When exein status is launched by the user, the Exein CLI checks that there is an active “.exein” project in the current directory. It then makes a request to the backend to know the current status of the Exein MLE models associated to that project.

Example

$ exein status



                       .__
    ____ ___  ___ ____ |__| ____
  _/ __ \\  \/  // __ \|  |/    \
  \  ___/ >    <\  ___/|  |   |  \
   \___  >__/\_ \\___  >__|___|  /
       \/      \/    \/        \/  Installer v0.3



[2021-01-13T09:38:55Z INFO ] Logged in as: giovanni@exein.io
+--------------------------------------+----------+--------------------------------+
| MODEL ID                             | STATUS   | CREATION DATE                  |
+--------------------------------------+----------+--------------------------------+
| 8b8bd444-6da1-4406-9781-4f4d58347d13 | TRAINING | 2021-01-13 09:38:15.505573 UTC |

This example retrieves all the active security models inside the current Exein project. An estimated time of completion is calculated. Also the status and the model score are reported as soon as they are available.

Note: model score is a statistical indicator of the trained model performances. Model score is calculated by evaluating the model against synthetic ad-hoc attacks that are spuriously injected into benign data. The score takes values in [0,1). A high-score (e.g. > 0.7) means that the model detects as anomaly even the slightest deviation from the device's normal behaviour. Model scores below 0.4 suggest to re-train the model using more robust data.

exein logout

Description

Logout of the Exein CLI during an active session.

Usage

exein logout

Arguments

This command takes no argument.

Extended Description

The command exein logout terminates the current active session, if any, logging the user out of the Exein API. When the user issues any new command after having logged out, they will be asked to login using their credentials.

Example

$ exein logout



                       .__
    ____ ___  ___ ____ |__| ____
  _/ __ \\  \/  // __ \|  |/    \
  \  ___/ >    <\  ___/|  |   |  \
   \___  >__/\_ \\___  >__|___|  /
       \/      \/    \/        \/  Installer v0.3



[2021-01-13T09:55:21Z INFO ] Logout successfully

This example simply logs you out of Exein CLI. The next time you run any Exein command, you will be asked to log in again.