doc/ndpi: move ndpi docs to new plugins section

Moves the nDPI documentation to an nDPI page in the plugins
section. Remove the duplication of installation and setup
documentation.

Includes some minor cleanups.

diff --git a/doc/userguide/Makefile.am b/doc/userguide/Makefile.am
index 356da45b99ce39af939fdc8a76c913cd3b0d06ee..1d9d485f990b30cf7cd5e9f35edd661e1fbbe303 100644 (file)
--- a/doc/userguide/Makefile.am
+++ b/doc/userguide/Makefile.am
@@ -23,6 +23,7 @@ EXTRA_DIST = \
        output \
        partials \
        performance \
+       plugins \
        public-data-sets.rst \
        quickstart.rst \
        reputation \

diff --git a/doc/userguide/index.rst b/doc/userguide/index.rst
index 7bfead762759143d9fdad35fe8c3fde6dbbd976d..3185ff9f09f4592989c732dfb2f9db5cc6702f56 100644 (file)
--- a/doc/userguide/index.rst
+++ b/doc/userguide/index.rst
@@ -29,6 +29,7 @@ This is the documentation for Suricata |version|.
    public-data-sets
    capture-hardware/index.rst
    unix-socket.rst
+   plugins/index.rst
    3rd-party-integration/index.rst
    manpages/index.rst
    acknowledgements

diff --git a/doc/userguide/plugins/index.rst b/doc/userguide/plugins/index.rst
new file mode 100644 (file)
index 0000000..e4854a7
--- /dev/null
+++ b/doc/userguide/plugins/index.rst
@@ -0,0 +1,8 @@
+Plugins
+=======
+
+Suricata bundles a few plugins that can't be built-in by default.
+
+.. toctree::
+
+   ndpi

diff --git a/doc/userguide/plugins/ndpi.rst b/doc/userguide/plugins/ndpi.rst
new file mode 100644 (file)
index 0000000..a07f2f5
--- /dev/null
+++ b/doc/userguide/plugins/ndpi.rst
@@ -0,0 +1,103 @@
+.. role:: example-rule-emphasis
+
+nDPI
+####
+
+Installation
+************
+
+Before using nDPI, Suricata must be built with nDPI support, for
+example:
+
+.. code-block:: console
+
+  ./configure --enable-ndpi --with-ndpi=/home/user/src/nDPI
+
+Then make sure the plugin is loaded in your ``suricata.yaml``:
+
+.. code-block:: yaml
+
+  plugins:
+    - /usr/lib/suricata/ndpi.so
+
+Which should also be present in the default configuration file after
+building Suricata with nDPI support.
+
+For more information on nDPI, see
+https://www.ntop.org/products/deep-packet-inspection/ndpi/.
+
+Keywords
+********
+
+Once the nDPI plugin is loaded, the following keyword are available:
+
+- ``ndpi-protocol``
+- ``ndpi-risk``
+
+``ndpi-protocol``
+=================
+
+Match on the Layer-7 protocol detected by nDPI.
+
+Note that rules using the ``ndpi-protocol`` should check if the
+``ndpi-protocol`` keyword exists with ``requires``, for example::
+
+  requires: keyword ndpi-protocol
+
+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"; :example-rule-emphasis:`requires:keyword ndpi-protocol; ndpi-protocol:TLS;` sid:1;)
+
+``ndpi-risk``
+=============
+
+Match on the flow risks detected by nDPI. Risks are potential issues
+detected by nDPI during the packet dissection and include:
+
+- Known protocol on non-standard port
+- Binary application transfer
+- Self-signed certificate
+- Suspected DGA Domain name
+- Malware host contacted
+- and many others...
+
+Additionally, rules using the ``ndpi-risk`` keyword should check if
+the keyword exists using the ``requires`` keyword, for example::
+
+  requires: keyword ndpi-risk
+
+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"; :example-rule-emphasis:`requires:keyword ndpi-protocol, keyword ndpi-risk; ndpi-protocol:HTTP; ndpi-risk:NDPI_BINARY_APPLICATION_TRANSFER;` sid:1;)

diff --git a/doc/userguide/rules/index.rst b/doc/userguide/rules/index.rst
index 1768c5075a47d09e1aa04742a946a096fbcb56d8..70b801311617a358ce2132f72b65d0951e038310 100644 (file)
--- a/doc/userguide/rules/index.rst
+++ b/doc/userguide/rules/index.rst
@@ -39,8 +39,6 @@ Suricata Rules
    websocket-keywords
    app-layer
    decode-layer
-   ndpi-protocol
-   ndpi-risk
    xbits
    noalert
    thresholding

diff --git a/doc/userguide/rules/ndpi-protocol.rst b/doc/userguide/rules/ndpi-protocol.rst
deleted file mode 100644 (file)
index 8cf924c..0000000
--- a/doc/userguide/rules/ndpi-protocol.rst
+++ /dev/null
@@ -1,43 +0,0 @@
-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
-
-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"; ndpi-protocol:TLS; sid:1;)
-

diff --git a/doc/userguide/rules/ndpi-risk.rst b/doc/userguide/rules/ndpi-risk.rst
deleted file mode 100644 (file)
index 41b36b7..0000000
--- a/doc/userguide/rules/ndpi-risk.rst
+++ /dev/null
@@ -1,49 +0,0 @@
-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 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
-
-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"; ndpi-protocol:HTTP; ndpi-risk:NDPI_BINARY_APPLICATION_TRANSFER; sid:1;)
-