.. include:: /keyword.rst

============
Exein Pulsar
============

`Pulsar`_ is a powerful and modular runtime security observability framework for the IoT, based on eBPF.

.. _Pulsar: https://pulsar.sh 

`Pulsar security framework`_ can be added existing Yocto images by adding the `meta-exein`_ layer.

The `meta-exein`_ layer depends on `meta-openembedded/meta-oe`_, `meta-rust-bin`_, and on these system tools:

.. _meta-exein: https://github.com/exein-io/meta-exein 
.. _Pulsar security framework: https://github.com/Exein-io/pulsar 
.. _meta-openembedded/meta-oe: https://github.com/openembedded/meta-openembedded 
.. _meta-rust-bin: https://github.com/rust-embedded/meta-rust-bin 


* ``clang`` >= 13
* ``llvm-strip`` >= 13

These instructions are applicable to IoT Yocto v24.1 which is based on Kirkstone (Yocto 4.0).
For later versions of Yocto, such as Yocto 5.0 Scarthgap, the `meta-rust-bin`_ layer is not needed.

.. note::

   MediaTek has worked with Exein to make ``meta-exein`` compatible with ``meta-mediatek-bsp``.
   For bussiness inquiries and technical support, please contact `Exein <https://www.exein.io/>`__ directly.

Prepare Yocto Build Environment
===============================

Prepare a Yocto build environment for you product images.

If you don't have a working build environment yet and would like to 
evaluate Pulsar on Genio EVK, follow :doc:`/sw/yocto/get-started` and
build ``rity-demo-image``. This creates a ``build`` directory containing
the Yocto build environment.

The steps below assumes that the build environment is ``build``.


Add Pulsar to Your Yocto Image
==============================

Add Exein Layer
---------------
1. Install system dependencies on your build machine. Example for Debian/Ubuntu:

.. prompt:: bash

   apt-get install clang llvm


2. Run the following command to download the ``meta-exein`` layer:

.. prompt:: bash

   git clone https://github.com/exein-io/meta-exein.git  -b kirkstone $PROJ_ROOT/src/meta-exein

3. Clone dependency layer  ``meta-openembedded/meta-oe``:

.. prompt:: bash

   git clone https://github.com/openembedded/meta-openembedded.git  -b kirkstone $PROJ_ROOT/src/meta-openembedded

4. Clone dependency layer ``meta-rust-bin``

.. prompt:: bash

   git clone https://github.com/rust-embedded/meta-rust-bin  $PROJ_ROOT/src/meta-rust-bin


Add Necessary Layers
--------------------

1. Add `meta-exein` and `meta-openembedded` layers to ``build/conf/bblayers.conf``

.. code-block::

    <absolute_path_to_rity>/meta-openembedded/meta-oe \
    <absolute_path_to_rity>/meta-exein \

and only for Yocto ``kirkstone``

.. code-block::

    <absolute_path_to_rity>/meta-rust-bin \


Add Necessary Configurations
----------------------------

1. Add the necessary configurations to the bottom of  ``build/conf/local.conf``

.. code-block::

    IMAGE_INSTALL:append = " pulsar"
    DISTRO_FEATURES:append = " btf"


Build Image
-----------

If you already have your own Yocto image recipe, simply build your image.

If you are evaluating on Genio EVK, follow :doc:`/sw/yocto/get-started` and
build ``rity-demo-image``.

Running Pulsar
==============

The following filesystems must be mounted: ``tracefs``, ``securityfs`` and
``cgroup2``. If not currently mounted, you can mount them by using the
following instructions **as root**:

mount tracefs:

.. prompt:: bash # auto

   # mount -t tracefs tracefs /sys/kernel/tracing

mount securityfs:

.. prompt:: bash # auto

   # mount -t securityfs securityfs /sys/kernel/security

mount cgroup2:

.. prompt:: bash # auto

   # mount -t cgroup2 cgroup2 /sys/fs/cgroup

To start Pulsar, run the follow command **as root**:

.. prompt:: bash # auto

   # pulsard
   [2024-11-29T12:15:45Z INFO  pulsar::pulsard::daemon] Starting module rules-engine
   [2024-11-29T12:15:45Z INFO  pulsar::pulsard::daemon] Starting module process-monitor
   [2024-11-29T12:15:46Z INFO  pulsar::pulsard::daemon] Starting module file-system-monitor
   [2024-11-29T12:15:46Z INFO  pulsar::pulsard::daemon] Starting module threat-logger

To check status of the daemon, on another terminal, run **as root**:

.. prompt:: bash # auto

   # pulsar status
   +---------------------+---------+
   | MODULE              | STATUS  |
   +=====================+=========+
   | desktop-notifier    | Created |
   +---------------------+---------+
   | file-system-monitor | Running |
   +---------------------+---------+
   | network-monitor     | Created |
   +---------------------+---------+
   | process-monitor     | Running |
   +---------------------+---------+
   | rules-engine        | Running |
   +---------------------+---------+
   | smtp-notifier       | Created |
   +---------------------+---------+
   | threat-logger       | Running |
   +---------------------+---------+


.. note::
    The rule files under ``/var/lib/pulsar/rules/`` should be considered as a generic examples only. You can customize
    the rules file to fit your system by adding exceptions to the default behavior.

For more information, and for learning how to interact with the Pulsar agent, please refer to the documentation
available `here <https://pulsar.sh/docs>`__.