8.50. Lua Scripting for Detection
There are 2 ways that Lua can be used with detection. These are
luarule keyword.luaxformtransform.
Note
As of Suricata 8.0, Lua rules are enabled by default and run in a sandboxed environment. See Lua Sandbox and Available functions.
8.50.1. 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.
8.50.1.1. Init function
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, Explicit rule hook (states) may be used. However, some buffers do require explicit initialization:
* ja3
* ja3s
* packet
* payload
* stream
To request these buffers, use an init method like:
function init (args)
return {packet = true}
end
8.50.1.2. Match function
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.
8.50.2. Lua Transform: luaxform
More details in luaxform.
8.50.3. 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, 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 Lua
Note
Suricata 8.0 has moved to Lua 5.4 and now has builtin support for bitwise and utf8 operations.
8.50.3.1. Script state and budgets
Each rule runs in one Lua state per thread, shared by every packet that thread processes for that rule, unrelated flows included. A value a script stores - a global, a cached table or handle - remains until the per-thread states are rebuilt (a rule reload) or the engine shuts down, and it is the script's own to manage: the engine-owned per-invocation context (flow, transactions, files) is refreshed by the engine on each call and reached only through the lib accessors.
The budgets are per invocation on top of that state. The instruction
counter is reset before every script call, so retained state costs no
instructions. Retained memory does count against the memory
allocation limit: the limit is the setup-time footprint plus
security.lua.max-bytes (0 disables it), fixed for the state's
life and not re-based between calls - so state a script keeps
reduces what later calls may allocate, and a script that caches more
than the limit fails its own later invocations with a memory limit
error. Keep state small and free what a call no longer needs.
A comprehensive list of existing lua functions - with examples - can be found at Lua functions (some of them, however, work only for the lua-output functionality).