transform: luaxform transform script

[jlucovsky]

Continuation of #12246

Add the luaxform transform that uses a Lua script to receive and transform a sticky buffer.

Lua transforms receive arguments

• (always): length of input buffer and input buffer
• (always): number of additional arguments (may be 0)
• (when present): argument array (bounded by argument count)

Arguments are passed to the Lua script as they appear in the rule:

 luaxform:./lua/lua-transform.lua, bytes 4, offset 13, hash sha256;

When the transform is invoked, 3 additional arguments are passed (arg count will be 3)

• bytes 4
• offset 13
• hash sha256

The Lua script is responsible for parsing and using the arguments and returning a tuple: output-buffer, output-buffer-byte-count

I used this Lua script:

function init (args)
  -- Optional, no return value
end

function transform(input_len, input, argc, args)
    SCLogNotice("Input length: " .. input_len .. " arg-count: " .. argc)
    for i = 1, argc do
        print("Argument " .. i .. ":", args[i])
    end
    return string.upper(input), input_len
end

return 0

Example rule using the Lua script:

alert http any any -> any any (msg:"Lua Xform example"; flow:established;  file.data; luaxform:./lua/lua-transform.lua; content: "abc"; sid: 1;)

Link to ticket: https://redmine.openinfosecfoundation.org/issues/2290

Describe changes:

• Luaxform transform changes

Updates

• Documentation clarifications per review
• Detect Lua function return value count correctly
• Formatting fixups.

Provide values to any of the below to override the defaults.

• To use an LibHTP, Suricata-Verify or Suricata-Update pull request,
  link to the pull request in the respective _BRANCH variable.
• Leave unused overrides blank or remove.

SV_REPO=
SV_BRANCH=OISF/suricata-verify#2090
SU_REPO=
SU_BRANCH=
LIBHTP_REPO=
LIBHTP_BRANCH=

[codecov]

Codecov Report

Attention: Patch coverage is 87.64045% with 55 lines in your changes missing coverage. Please review.

Project coverage is 83.21%. Comparing base (a9b36d8) to head (77a091b).

Additional details and impacted files

@@            Coverage Diff             @@
##           master   #12247      +/-   ##
==========================================
+ Coverage   83.18%   83.21%   +0.03%     
==========================================
  Files         912      914       +2     
  Lines      257174   257389     +215     
==========================================
+ Hits       213930   214192     +262     
+ Misses      43244    43197      -47     

Flag	Coverage Δ
fuzzcorpus	60.99% <47.11%> (-0.02%)	⬇️
livemode	19.41% <13.16%> (+<0.01%)	⬆️
pcap	44.35% <30.25%> (-0.05%)	⬇️
suricata-verify	62.79% <85.21%> (+<0.01%)	⬆️
unittests	59.15% <26.51%> (-0.04%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

[suricata-qa]

Information: QA ran without warnings.

Pipeline 23724

[jufajardini]

From my end, I think that the section's organization is the only thing missing, at this point. Thanks for tackling the feedback so far.

As I can't edit regions that were not changed, the full diff would look like this (I checked the result with make html and it looks correct, but ofc do adjust if the hierarchy looks off or should be different):

diff --git a/doc/userguide/rules/lua-detection.rst b/doc/userguide/rules/lua-detection.rst
index 2a8ed241e..4dfeeaf00 100644
--- a/doc/userguide/rules/lua-detection.rst
+++ b/doc/userguide/rules/lua-detection.rst
@@ -29,7 +29,7 @@ A Lua rule script has 2 required functions, an ``init`` function and
 Additionally, the script will run in a limited sandbox by default.
 
 Init function
--------------
+^^^^^^^^^^^^^
 
 .. code-block:: lua
 
@@ -70,7 +70,7 @@ All the HTTP buffers have a limitation: only one can be inspected by a
 script at a time.
 
 Match function
---------------
+^^^^^^^^^^^^^^
 
 .. code-block:: lua
 
@@ -112,12 +112,12 @@ Entire script:
   return 0
 
 Lua Transform: ``luaxform``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------
 
 More details in :ref:`lua-transform`.
 
 Lua Sandbox and Available functions
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-----------------------------------

[jlucovsky]

Continued in #12251