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