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;) -