mirror of https://github.com/OISF/suricata
You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
128 lines
3.4 KiB
ReStructuredText
128 lines
3.4 KiB
ReStructuredText
.. _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).
|