userguide/lua: add explanation about `need` diffs

[people/ms/suricata.git] / doc / userguide / lua / lua-functions.rst

diff --git a/doc/userguide/lua/lua-functions.rst b/doc/userguide/lua/lua-functions.rst
index a50ab02a196cb7ad8ec5d462f9121f9689109a99..218b84939db61120d286461dfdef63d2e2606d4b 100644 (file)
--- 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