8.49. 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 Lua Sandbox and Available functions.

8.49.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.49.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.49.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.49.2. Lua Transform: `luaxform`

More details in luaxform.

8.49.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, 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 Lua

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 Lua functions (some of them, however, work only for the lua-output functionality).