.. _lua-functions:

Lua functions
=============

Differences between `output` and `detect`:
------------------------------------------

Currently the ``table`` returned from the ``init`` method varies,
depending on whether it is in an output script or a detection script.

Lua scripts for ``luaxform`` do not require an ``init`` method.

If the script is for detection, the ``init`` method should return a
table, for example, if a packet is required:

.. code-block:: lua

  function init (args)
    local needs = {}
    needs["packet"] = true
    return needs
  end

See :ref:`lua-detection` for more detection script examples.

For output scripts, follow the pattern below. (The complete script
structure can be seen at :ref:`lua-output`:)

.. code-block:: lua

  function init (args)
      local needs = {}
      needs["protocol"] = "tls"
      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.

.. note:: By convention, many scripts use a variable name of ``needs``
          for this table, however this is not a hard requirement.

packet
------

Initialize with:

::

  function init (args)
      local needs = {}
      needs["type"] = "packet"
      return needs
  end


flow
----

::

  function init (args)
      local needs = {}
      needs["type"] = "flow"
      return needs
  end

http
----

For output, init with:

::

  function init (args)
      local needs = {}
      needs["protocol"] = "http"
      return needs
  end

For detection, rule hooks are used to execute the Lua script at
specific protocol states, for example::

  alert http1:request_line any any -> any any (
      msg: "Test HTTP Lua request.line";
      lua: test-request-line.lua; sid:1;)

where ``test-request-line.lua`` might look like:

.. code-block:: lua

  local http = require("suricata.http")

  function init (args)
    return {}
  end

  function match(args)
    local tx, err = http.get_tx()
    http_request_line, err = tx:request_line()

    if #http_request_line > 0 then
        --GET /base64-hello-world.txt HTTP/1.1
        if http_request_line:find("^GET") then
            return 1
        end
    end

    return 0
  end

For more information on rule hooks, see :ref:`rule-hooks`.

Streaming Data
--------------

Streaming data can currently log out reassembled TCP data and
normalized HTTP data. The script will be invoked for each consecutive
data chunk.

In case of TCP reassembled data, all possible overlaps are removed
according to the host OS settings.

::

  function init (args)
      return {streaming = "tcp"}
  end

In case of HTTP body data, the bodies are unzipped and dechunked if applicable.

::

  function init (args)
      return {streaming = "http"}
  end

The streaming data will be provided in the ``args`` to the log
function within a ``stream`` subtable::

  function log(args)
    -- The data (buffer)
    local data = args["stream"]["data"]

    -- Buffer open?
    local open = args["stream"]["open"]

    -- Buffer closed?
    local close = args["stream"]["close"]

    -- To server?
    local ts = args["stream"]["to_server"]

    -- To client?
    local tc = args["stream"]["to_client"]
  end