From: Jason Ish Date: Fri, 24 Jan 2025 16:51:45 +0000 (-0600) Subject: doc/ndpi: move ndpi docs to new plugins section X-Git-Tag: suricata-8.0.0-beta1~177 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=66eb29affd0a5efc8aee50c73a904b89df2311c5;p=thirdparty%2Fsuricata.git 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 356da45b99..1d9d485f99 100644 --- 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 7bfead7627..3185ff9f09 100644 --- 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 index 0000000000..e4854a797e --- /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 index 0000000000..a07f2f5707 --- /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:[!]; + +Where `` 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:[!]; + +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 1768c5075a..70b8013116 100644 --- 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 index 8cf924cac6..0000000000 --- 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:[!]; - -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 index 41b36b700d..0000000000 --- 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:[!]; - -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;) -