From: Jason Ish <jason.ish@oisf.net>
Date: Mon, 28 Jul 2025 22:23:41 +0000 (-0600)
Subject: doc/lua-detection: fix example script; remove most buffers
X-Git-Url: http://git.ipfire.org/gitweb/gitweb.cgi?a=commitdiff_plain;h=7a65ca10e27713930f26f7400321da201a106a75;p=thirdparty%2Fsuricata.git

doc/lua-detection: fix example script; remove most buffers

- Reference rule hooks instead

Ticket: #7728
---

diff --git a/doc/userguide/rules/lua-detection.rst b/doc/userguide/rules/lua-detection.rst
index 5f58e5b065..633476b0a3 100644
--- a/doc/userguide/rules/lua-detection.rst
+++ b/doc/userguide/rules/lua-detection.rst
@@ -33,66 +33,37 @@ Init function
 .. code-block:: lua
 
   function init (args)
-      local needs = {}
-      needs["http.request_line"] = tostring(true)
-      return needs
+      return {}
   end
 
-The init function registers the buffer(s) that need
-inspection. Currently the following are available:
+Most Lua rule scripts can simply return an empty table in their init
+method. To hook into specific protocols states, :ref:`rule-hooks` may
+be used. However, some buffers do require explicit initialization::
 
-* packet -- entire packet, including headers
-* payload -- packet payload (not stream)
-* buffer -- the current sticky buffer
+* ja3
+* ja3s
+* packet
+* payload
 * stream
-* dnp3
-* ssh
-* smtp
-* tls
-* http.uri
-* http.uri.raw
-* http.request_line
-* http.request_headers
-* http.request_headers.raw
-* http.request_body
-* http.response_headers
-* http.response_headers.raw
-* http.response_body
-
-All the HTTP buffers have a limitation: only one can be inspected by a
-script at a time.
 
-Match function
-^^^^^^^^^^^^^^
+To request these buffers, use an ``init`` method like:
 
 .. code-block:: lua
 
-  function match(args)
-      a = tostring(args["http.request_line"])
-      if #a > 0 then
-          if a:find("^POST%s+/.*%.php%s+HTTP/1.0$") then
-              return 1
-          end
-      end
-
-      return 0
+  function init (args)
+    return {packet = true}
   end
 
-The script can return 1 or 0. It should return 1 if the condition(s)
-it checks for match, 0 if not.
-
-Entire script:
+Match function
+^^^^^^^^^^^^^^
 
 .. code-block:: lua
 
-  function init (args)
-      local needs = {}
-      needs["http.request_line"] = tostring(true)
-      return needs
-  end
+  local http = require("suricata.http")
 
   function match(args)
-      a = tostring(args["http.request_line"])
+      local tx = http.get_tx()
+      a = tx:request_line()
       if #a > 0 then
           if a:find("^POST%s+/.*%.php%s+HTTP/1.0$") then
               return 1
@@ -102,7 +73,8 @@ Entire script:
       return 0
   end
 
-  return 0
+The script can return 1 or 0. It should return 1 if the condition(s)
+it checks for match, 0 if not.
 
 Lua Transform: ``luaxform``
 ---------------------------