.. _lua-detection:

Lua Scripting for Detection
===========================

There are 2 ways that Lua can be used with detection. These are

* ``lua`` rule keyword.
* ``luaxform`` transform.

.. note:: As of Suricata 8.0, Lua rules are enabled by default and run
          in a sandboxed environment. See :ref:`lua-sandbox`.

Lua Rule Keyword
----------------

Syntax:

::

  lua:[!]<scriptfilename>;

The script filename will be appended to your default rules location.

A Lua rule script has 2 required functions, an ``init`` function and
``match`` function, discussed below.

Additionally, the script will run in a limited sandbox by default.

Init function
^^^^^^^^^^^^^

.. code-block:: lua

  function init (args)
      return {}
  end

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::

* ja3
* ja3s
* packet
* payload
* stream

To request these buffers, use an ``init`` method like:

.. code-block:: lua

  function init (args)
    return {packet = true}
  end

Match function
^^^^^^^^^^^^^^

.. code-block:: lua

  local http = require("suricata.http")

  function match(args)
      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
          end
      end

      return 0
  end

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``
---------------------------

More details in :ref:`lua-transform`.

.. _lua-sandbox:

Lua Sandbox and Available functions
-----------------------------------

Lua rule scripts are run in a sandbox environment the applies the
following restrictions:

* reduced libraries
* only allowed functions available
* instruction count limit
* memory allocation limit

The following table lists the library and functions available:

==================  =================================================================
Package Name        Functions
==================  =================================================================
base                assert, ipairs, next, pairs, print, rawequal, rawlen, select, 
                    tonumber, tostring, type, warn, rawget, rawset, error
table               concat, insert, move, pack, remove, sort, unpack
string              byte, char, dump, find, format, gmatch, gsub, len, lower, match, 
                    pack, packsize, rep, reverse, sub, unpack, upper
math                abs, acos, asin, atan, atan2, ceil, cos, cosh, deg, exp, floor, 
                    fmod, frexp, ldexp, log, log10, max, min, modf, pow, rad, random, 
                    randomseed, sin, sinh, sqrt, tan, tanh, tointeger, type, ult
utf8                offset, len, codes, char, codepoint
==================  =================================================================

Of note, the following standard libraries are not available:

* coroutine
* package
* input and output
* operating system facilities
* debug

This behavior can be modified via the ``security.lua`` section of :ref:`suricata-yaml-lua-config`

.. note:: Suricata 8.0 has moved to Lua 5.4 and now has builtin support for bitwise and utf8 operations.

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).