ndpi: ndpi as a plugin - v6

.github/workflows/builds.yml

@@ -628,9 +628,19 @@ jobs:
         uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16
         with:
           name: dist
+
+      - name: Build and install nDPI
+        run: |
+          curl -OL https://github.com/ntop/nDPI/archive/refs/tags/4.12.tar.gz
+          tar xvf 4.12.tar.gz
+          cd nDPI-4.12
+          ./autogen.sh
+          ./configure
+          make -j ${{ env.CPUS }}
+
       - run: tar zxvf suricata-*.tar.gz --strip-components=1
       - name: ./configure
-        run: CFLAGS="${DEFAULT_CFLAGS}" ./configure
+        run: CFLAGS="${DEFAULT_CFLAGS}" ./configure --enable-ndpi --with-ndpi=$(pwd)/nDPI-4.12
       - run: make -j ${{ env.CPUS }}
       - run: make install
       - run: make install-conf
@@ -648,6 +658,8 @@ jobs:
         with:
           name: prep
           path: prep
+      - name: Check if the nDPI plugin was installed
+        run: test -e /usr/local/lib/suricata/ndpi.so
       - run: tar xf prep/suricata-verify.tar.gz
       - run: python3 ./suricata-verify/run.py -q --debug-failed
       - run: suricata-update -V

configure.ac

@@ -2309,6 +2309,57 @@ fi
     ])
     AC_SUBST(RUST_FEATURES)
 
+# nDPI support (no library checks for this stub)
+    NDPI_HOME=
+    AC_ARG_ENABLE(ndpi,
+           AS_HELP_STRING([--enable-ndpi], [Enable nDPI support]),
+           [enable_ndpi=$enableval],[enable_ndpi=no])
+    AC_ARG_WITH([ndpi],
+           [  --with-ndpi=<path>    path to nDPI source tree.],
+           [NDPI_HOME="$withval"])
+
+    # Require --with-ndpi to be provided with an argument.
+    AS_IF([test "x$NDPI_HOME" = "xyes"], [
+        AC_MSG_ERROR([--with-ndpi requires a path])
+        exit 1
+    ])
+
+    AS_IF([test "x$enable_dpi" = "xyes"], [
+        if test "x$enable_shared" = "xno"; then
+            echo
+            echo "   ERROR! ndpi cannot be enabled with --disable-shared"
+            echo
+            exit 1
+        fi
+    ])
+
+    if test "x$enable_ndpi" = "xyes"; then
+        AC_MSG_CHECKING(for nDPI source)
+        if test "x$NDPI_HOME" != "x"; then
+            AC_MSG_RESULT(found in $NDPI_HOME)
+            NDPI_LIB=$NDPI_HOME/src/lib/libndpi.a
+            AC_MSG_CHECKING(for $NDPI_LIB)
+            if test -r $NDPI_LIB ; then :
+                AC_MSG_RESULT(found $NDPI_LIB)
+            fi
+            CPPFLAGS="${CPPFLAGS} -I$NDPI_HOME/src/include"
+            NDPI_LIB="$NDPI_HOME/src/lib/libndpi.a"
+            AC_SUBST([NDPI_LIB])
+        else
+            AC_MSG_RESULT(not found)
+            enable_ndpi="no"
+        fi
+    fi
+
+    if test "x$enable_ndpi" = "xyes"; then
+        AM_CONDITIONAL([BUILD_NDPI], [true])
+        ndpi_comment=""
+    else
+        AM_CONDITIONAL([BUILD_NDPI], [false])
+        ndpi_comment="#"
+    fi
+    AC_SUBST([ndpi_comment])
+
     AC_ARG_ENABLE(warnings,
            AS_HELP_STRING([--enable-warnings], [Enable supported C compiler warnings]),[enable_warnings=$enableval],[enable_warnings=no])
     AS_IF([test "x$enable_warnings" = "xyes"], [
@@ -2530,6 +2581,7 @@ AC_CONFIG_FILES(examples/lib/simple/Makefile examples/lib/simple/Makefile.exampl
 AC_CONFIG_FILES(plugins/Makefile)
 AC_CONFIG_FILES(plugins/pfring/Makefile)
 AC_CONFIG_FILES(plugins/napatech/Makefile)
+AC_CONFIG_FILES(plugins/ndpi/Makefile)
 
 AC_OUTPUT
 
@@ -2585,6 +2637,9 @@ SURICATA_BUILD_CONF="Suricata Configuration:
   Plugin support (experimental):           ${plugin_support}
   DPDK Bond PMD:                           ${enable_dpdk_bond_pmd}
 
+Plugins:
+  nDPI:                                    ${enable_ndpi}
+
 Development settings:
   Coccinelle / spatch:                     ${enable_coccinelle}
   Unit tests enabled:                      ${enable_unittests}

doc/userguide/rules/index.rst

@@ -38,6 +38,8 @@ Suricata Rules
    smtp-keywords
    websocket-keywords
    app-layer
+   ndpi-protocol
+   ndpi-risk
    xbits
    noalert
    thresholding

doc/userguide/rules/ndpi-protocol.rst

@@ -0,0 +1,48 @@
+nDPI Protocol Keyword
+=====================
+
+ndpi-protocol
+-------------
+
+Match on the Layer-7 protocol detected by nDPI.
+
+Suricata should be compiled with the nDPI support and the ``ndpi`` 
+plugin must be loaded before it can be used. 
+
+Example of configuring Suricata to be compiled with nDPI support:
+
+.. code-block:: console
+
+    ./configure --enable-ndpi --with-ndpi=/home/user/nDPI
+
+Note that rules using the ``ndpi-protocol`` should check if the
+``ndpi-protocol`` keyword exists with ``requires``, for example::
+
+  requires: keyword ndpi-protocol
+
+Example of suricata.yaml configuration file to load the ``ndpi`` plugin::
+
+  plugins:
+    - /usr/lib/suricata/ndpi.so
+
+Syntax::
+
+    ndpi-protocol:[!]<protocol>;
+
+Where protocol is one of the application protocols detected by nDPI.
+Plase check ndpiReader -H for the full list.
+It is possible to specify the transport protocol, the application
+protocol, or both (dot-separated).
+
+Examples::
+
+    ndpi-protocol:HTTP;
+    ndpi-protocol:!TLS;
+    ndpi-protocol:TLS.YouTube;
+
+Here is an example of a rule matching TLS traffic on port 53:
+
+.. container:: example-rule
+
+    alert tcp any any -> any 53 (msg:"TLS traffic over DNS standard port"; requires: keyword ndpi-protocol; ndpi-protocol:TLS; sid:1;)
+

doc/userguide/rules/ndpi-risk.rst

@@ -0,0 +1,54 @@
+nDPI Risk Keyword
+=================
+
+ndpi-risk
+---------
+
+Match on the flow risks detected by nDPI. Risks are potential issues detected
+by nDPI during the packet dissection and include:
+
+- Known Proto on Non Std Port
+- Binary App Transfer
+- Self-signed Certificate
+- Susp DGA Domain name
+- Malware host contacted
+- and many other...
+
+Suricata should be compiled with nDPI support and the ``ndpi`` plugin
+must be loaded before it can be used.
+
+Additionally, rules using the ``ndpi-risk`` keyword should check if
+the keyword exists using the ``requires`` keyword, for example::
+
+  ``requires: keyword ndpi-risk``
+
+Example of configuring Suricata to be compiled with nDPI support:
+
+.. code-block:: console
+
+    ./configure --enable-ndpi --with-ndpi=/home/user/nDPI
+
+Example of suricata.yaml configuration file to load the ``ndpi`` plugin::
+
+  plugins:
+    - /usr/lib/suricata/ndpi.so
+
+Syntax::
+
+    ndpi-risk:[!]<risk>;
+
+Where risk is one (or multiple comma-separated) of the risk codes supported by
+nDPI (e.g. NDPI_BINARY_APPLICATION_TRANSFER). Please check ndpiReader -H for the
+full list.
+
+Examples::
+
+    ndpi-risk:NDPI_BINARY_APPLICATION_TRANSFER;
+    ndpi-risk:NDPI_TLS_OBSOLETE_VERSION,NDPI_TLS_WEAK_CIPHER;
+
+Here is an example of a rule matching HTTP traffic transferring a binary application:
+
+.. container:: example-rule
+
+    alert tcp any any -> any any (msg:"Binary application transfer over HTTP"; requires: keyword ndpi-protocol, keyword ndpi-risk; ndpi-protocol:HTTP; ndpi-risk:NDPI_BINARY_APPLICATION_TRANSFER; sid:1;)
+

etc/schema.json

@@ -6866,6 +6866,10 @@
                 }
             },
             "additionalProperties": false
+        },
+        "ndpi": {
+            "description": "nDPI plugin",
+            "type": "object"
         }
     },
     "$defs": {

plugins/Makefile.am

@@ -7,3 +7,7 @@ endif
 if BUILD_NAPATECH
 SUBDIRS += napatech
 endif
+
+if BUILD_NDPI
+SUBDIRS += ndpi
+endif

plugins/ndpi/Makefile.am

@@ -0,0 +1,13 @@
+pkglib_LTLIBRARIES = ndpi.la
+
+ndpi_la_LDFLAGS = -module -avoid-version -shared
+ndpi_la_LIBADD = @NDPI_LIB@
+
+# Only required to find these headers when building plugins from the
+# source directory.
+ndpi_la_CFLAGS = -I../../rust/gen -I../../rust/dist
+
+ndpi_la_SOURCES = ndpi.c
+
+install-exec-hook:
+	cd $(DESTDIR)$(pkglibdir) && $(RM) $(pkglib_LTLIBRARIES)