1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
|
.. _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).
|
