.. _Suricata Integration:

Suricata Integration
====================

ntopng integrates with `Suricata <https://suricata-ids.org>`_ for importing
both *flow* metadata (Suricata acts as a sensor) and *alerts*.
Alerts ingestion allows ntopng to complement the built-in traffic analysis 
engine with the flexible signature-based threats detection capabilities 
provided by Suricata.

ntopng implements flows and alerts ingestion from Suricata using the *Eve 
JSON* format through syslog. 

.. warning::

   This is a new feature available in ntopng since version 3.9.

In order to configure Suricata to export flow metadata to ntopng, please install 
Suricata according to the `Suricata Documentation <https://suricata.readthedocs.io/en/suricata-4.1.4/install.html>`_
and configure it to use :code:`syslog` as EVE file type in the :code:`suricata.yaml`
configuration file (this is usually located under :code:`/etc/suricata/suricata.yaml` or :code:`/usr/local/etc/suricata/suricata.yaml`):

.. code:: text

     - eve-log:
         enabled: yes
         filetype: syslog

Flows Export
~~~~~~~~~~~~

If you are already processing traffic with ntopng (mirroring the same traffic 
to Suricata and ntopng), flows export from Suricata is not required as ntopng 
is already computing flows, in addition to other traffic analysis activities 
that are not always possible when collecting flows from Suricata rather then 
looking at raw traffic.

Instead, if you want to use Suricata as sensor for exporting flow metadata to 
ntopng, you also need to enable :code:`netflow` in the :code:`suricata.yaml`
configuration file:

.. code:: text

        - netflow

Syslog Configuration
~~~~~~~~~~~~~~~~~~~~

Please check the *Syslog Configuration* paragraph in the `Syslog Log Ingestion`_ section
for instructions to configure *rsyslog*.

Run Suricata
~~~~~~~~~~~~

At this point you should be able to run Suricata to start exporting alerts
(and flows) through syslog:

.. code:: bash

   suricata -c /etc/suricata/suricata.yaml -i eth1

ntopng Configuration
~~~~~~~~~~~~~~~~~~~~

As last step, you should configure ntopng to ingest syslog messages by adding
the Syslog interface :code:`syslog://<ip>:<port>` to the configuration file
to listen for connections to the specified <ip> and <port>.

If you are using Suricata for exporting flow metadata, and you enabled 
:code:`netflow` in in the :code:`suricata.yaml` configuration file, you
do not need to configure additional interfaces in ntopng. Otherwise you
need to also configure the interface (e.g. eth1) with live traffic.

Example:

.. code:: text

   -i=syslog://127.0.0.1:9999
   -i=eth1

Please remember to *restart* the *ntopng* service to apply the change.

If you configured two interfaces in ntopng, the syslog interface for 
ingesting alerts, and the network interface for processing traffic, you
need to instruct ntopng to bind alerts to traffic. This can be achieved
by configure the syslog interface as companion interface for the network
interface through the interface configuration page in the ntopng Web GUI.

1. Go to **Interfaces** -> **(interface)** -> **Settings** and select **Mirrored Traffic**.
2. Go to **Interfaces** -> **(interface)** -> **Settings** and select the syslog interface in the **Companion Interface** dropdown.
3. Save

At this point the packet interface should be able to process and show the 
alerts generated by Suricata and let you drill down to traffic and packets.

.. _`Syslog Log Ingestion`: ../advanced_features/syslog.html

Suricata Acceleration
=====================

Read the `IDS Acceleration <https://www.ntop.org/guides/ntopng/advanced_features/ids_acceleration.html>`_ 
section to learn how to accelerate the Suricata performance with both PF_RING and ntopng.