From: Juliana Fajardini <jufajardini@gmail.com>
Date: Thu, 14 Oct 2021 21:42:11 +0000 (+0100)
Subject: userguide/lua: add explanation about `need` diffs
X-Git-Tag: suricata-7.0.0-beta1~1148
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e7f1736f3ab512d9d63e92152a984bf64c27039b;p=thirdparty%2Fsuricata.git

userguide/lua: add explanation about `need` diffs

The differences on how the `need` key works, depending on script
usage (output or detection) confuses users, sometimes (cf doc#4725).
While we don't fix that, just explain this behavior.
---

diff --git a/doc/userguide/lua/lua-functions.rst b/doc/userguide/lua/lua-functions.rst
index a50ab02a19..218b84939d 100644
--- a/doc/userguide/lua/lua-functions.rst
+++ b/doc/userguide/lua/lua-functions.rst
@@ -3,6 +3,35 @@
 Lua functions
 =============
 
+Differences between `output` and `detect`:
+------------------------------------------
+
+Currently, the ``needs`` key initialization varies, depending on what is the goal of the script: output or detection.
+
+If the script is for detection, the ``needs`` initialization should be as seen in the example below (see :ref:`lua-scripting` for a complete example for a detect script):
+
+::
+
+  function init (args)
+      local needs = {}
+      needs["packet"] = tostring(true)
+      return needs
+  end
+
+For output logs, follow the pattern below. (The complete script structure can be seen at :ref:`lua-output`:)
+
+::
+
+  function init (args)
+      local needs = {}
+      needs["protocol"] = "http"
+      return needs
+  end
+
+
+Do notice that the functions and protocols available for ``log`` and ``match`` may also vary. DNP3, for instance, is not
+available for logging.
+
 packet
 ------
 
@@ -159,7 +188,7 @@ notation. To avoid that, simply do:
 http
 ----
 
-Init with:
+For output, init with:
 
 ::
 
@@ -169,6 +198,16 @@ Init with:
       return needs
   end
 
+For detection, use the specific buffer (cf :ref:`lua-detection` for a complete list), as with:
+
+::
+
+  function init (args)
+      local needs = {}
+      needs["http.uri"] = tostring(true)
+      return needs
+  end
+
 HttpGetRequestBody and HttpGetResponseBody.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -297,6 +336,27 @@ HttpGetResponseHeaders
 DNS
 ---
 
+If your purpose is to create a logging script, initialize the buffer as:
+
+::
+
+  function init (args)
+     local needs = {}
+     needs["protocol"] = "dns"
+     return needs
+  end
+
+If you are going to use the script for rule matching, choose one of the available DNS buffers listed in
+:ref:`lua-detection` and follow the pattern:
+
+::
+
+  function init (args)
+     local needs = {}
+     needs["dns.rrname"] = tostring(true)
+     return needs
+  end
+
 DnsGetQueries
 ~~~~~~~~~~~~~
 
@@ -383,7 +443,7 @@ returns a bool
 TLS
 ---
 
-Initialize with:
+For log output, initialize with:
 
 ::
 
@@ -393,6 +453,16 @@ Initialize with:
       return needs
   end
 
+For detection, initialization is as follows:
+
+::
+
+  function init (args)
+      local needs = {}
+      needs["tls"] = tostring(true)
+      return needs
+  end
+
 TlsGetVersion
 ~~~~~~~~~~~~~
 
@@ -519,7 +589,7 @@ JA3
 
 JA3 must be enabled in the Suricata config file (set 'app-layer.protocols.tls.ja3-fingerprints' to 'yes').
 
-Initialize with:
+For log output, initialize with:
 
 ::
 
@@ -529,6 +599,16 @@ Initialize with:
       return needs
   end
 
+For detection, initialization is as follows:
+
+::
+
+  function init (args)
+      local needs = {}
+      needs["tls"] = tostring(true)
+      return needs
+  end
+
 Ja3GetHash
 ~~~~~~~~~~
 
@@ -566,7 +646,7 @@ Ja3SGetHash
 
 Get the JA3S hash (md5sum of JA3S string) through JA3SGetHash.
 
-Example:
+Examples:
 
 ::
 
@@ -577,12 +657,27 @@ Example:
       end
   end
 
+Or, for detection:
+
+::
+
+  function match (args)
+      hash = Ja3SGetHash()
+      if hash == nil then
+        return 0
+      end
+
+      // matching code
+
+      return 0
+  end
+
 JA3SGetString
 ~~~~~~~~~~~~~
 
 Get the JA3S string through Ja3SGetString.
 
-Example:
+Examples:
 
 ::
 
@@ -593,6 +688,21 @@ Example:
       end
   end
 
+Or, for detection:
+
+::
+
+  function match (args)
+    str = Ja3SGetString()
+    if str == nil then
+      return 0
+    end
+
+    // matching code
+
+    return 0
+  end
+
 SSH
 ---
 
@@ -600,7 +710,6 @@ Initialize with:
 
 ::
 
-
   function init (args)
       local needs = {}
       needs["protocol"] = "ssh"
@@ -632,7 +741,6 @@ Example:
 
 ::
 
-
   function log (args)
       software = SshGetServerSoftwareVersion()
       if software == nil then
diff --git a/doc/userguide/lua/lua-usage.rst b/doc/userguide/lua/lua-usage.rst
index 32b562ca62..091f46e7e9 100644
--- a/doc/userguide/lua/lua-usage.rst
+++ b/doc/userguide/lua/lua-usage.rst
@@ -4,9 +4,11 @@ Lua usage in Suricata
 Lua scripting can be used in two components of Suricata. The first is in
 output and the second one in rules in the detection engine.
 
-Both features are using a list of functions to access to data extracted by
+Both features are using a list of functions to access the data extracted by
 Suricata. You can get the list of functions in the :ref:`lua-functions` page.
 
+.. note:: Currently, there is a difference in the ``needs`` key in the ``init`` function, depending on what is the usage: ``output`` or ``detection``. The list of available functions may also differ.
+
 Lua output
 ----------
 
diff --git a/doc/userguide/rules/rule-lua-scripting.rst b/doc/userguide/rules/rule-lua-scripting.rst
index 53eddb7c58..31d671bd27 100644
--- a/doc/userguide/rules/rule-lua-scripting.rst
+++ b/doc/userguide/rules/rule-lua-scripting.rst
@@ -16,7 +16,6 @@ The script has 2 parts, an init function and a match function. First, the init.
 Init function
 -------------
 
-
 .. code-block:: lua
 
   function init (args)
@@ -88,3 +87,6 @@ Entire script:
   end
 
   return 0
+
+A comprehensive list of existing lua functions -  with examples - can be found at :ref:`lua-functions` (some of them, however,
+work only for the lua-output functionality).