18.2. Lua functions

18.2.1. Differences between output and detect:

Currently, the needs key initialization varies, depending on what is the goal of the script: output or detection.

If the script is for detection, the needs initialization should be as seen in the example below (see Lua Scripting for Detection for a complete example of a detection script):

function init (args)
    local needs = {}
    needs["packet"] = tostring(true)
    return needs
end

For output logs, follow the pattern below. (The complete script structure can be seen at Lua Output:)

function init (args)
    local needs = {}
    needs["protocol"] = "http"
    return needs
end

Do notice that the functions and protocols available for log and match may also vary. DNP3, for instance, is not available for logging.

18.2.2. packet

Initialize with:

function init (args)
    local needs = {}
    needs["type"] = "packet"
    return needs
end

18.2.3. flow

function init (args)
    local needs = {}
    needs["type"] = "flow"
    return needs
end

18.2.4. http

For output, init with:

function init (args)
    local needs = {}
    needs["protocol"] = "http"
    return needs
end

For detection, use the specific buffer (cf Lua Scripting for Detection for a complete list), as with:

function init (args)
    local needs = {}
    needs["http.uri"] = tostring(true)
    return needs
end

18.2.4.1. HttpGetRequestBody and HttpGetResponseBody.

Make normalized body data available to the script through HttpGetRequestBody and HttpGetResponseBody.

There no guarantees that all of the body will be available.

Example:

function log(args)
    a, o, e = HttpGetResponseBody();
    --print("offset " .. o .. " end " .. e)
    for n, v in ipairs(a) do
        print(v)
    end
end

18.2.4.2. HttpGetRequestHost

Get the host from libhtp's htp_tx_request_hostname(tx), which can either be the host portion of the url or the host portion of the Host header.

Example:

http_host = HttpGetRequestHost()
if http_host == nil then
    http_host = "<hostname unknown>"
end

18.2.4.3. HttpGetRequestHeader

http_ua = HttpGetRequestHeader("User-Agent")
if http_ua == nil then
    http_ua = "<useragent unknown>"
end

18.2.4.4. HttpGetResponseHeader

server = HttpGetResponseHeader("Server");
print ("Server: " .. server);

18.2.4.5. HttpGetRequestLine

rl = HttpGetRequestLine();
print ("Request Line: " .. rl);

18.2.4.6. HttpGetResponseLine

rsl = HttpGetResponseLine();
print ("Response Line: " .. rsl);

18.2.4.7. HttpGetRawRequestHeaders

rh = HttpGetRawRequestHeaders();
print ("Raw Request Headers: " .. rh);

18.2.4.8. HttpGetRawResponseHeaders

rh = HttpGetRawResponseHeaders();
print ("Raw Response Headers: " .. rh);

18.2.4.9. HttpGetRequestUriRaw

http_uri = HttpGetRequestUriRaw()
if http_uri == nil then
    http_uri = "<unknown>"
end

18.2.4.10. HttpGetRequestUriNormalized

http_uri = HttpGetRequestUriNormalized()
if http_uri == nil then
    http_uri = "<unknown>"
end

18.2.4.11. HttpGetRequestHeaders

a = HttpGetRequestHeaders();
for n, v in pairs(a) do
    print(n,v)
end

18.2.4.12. HttpGetResponseHeaders

a = HttpGetResponseHeaders();
for n, v in pairs(a) do
    print(n,v)
end

18.2.5. TLS

For log output, initialize with:

function init (args)
    local needs = {}
    needs["protocol"] = "tls"
    return needs
end

For detection, initialization is as follows:

function init (args)
    local needs = {}
    needs["tls"] = tostring(true)
    return needs
end

18.2.5.1. TlsGetVersion

Get the negotiated version in a TLS session as a string through TlsGetVersion.

Example:

function log (args)
    version = TlsGetVersion()
    if version then
        -- do something
    end
end

18.2.5.2. TlsGetCertInfo

Make certificate information available to the script through TlsGetCertInfo.

Example:

function log (args)
    version, subject, issuer, fingerprint = TlsGetCertInfo()
    if version == nil then
        return 0
    end
end

18.2.5.3. TlsGetCertChain

Make certificate chain available to the script through TlsGetCertChain.

The output is an array of certificate with each certificate being an hash with data and length keys.

Example:

-- Use debian lua-luaossl coming from https://github.com/wahern/luaossl
local x509 = require"openssl.x509"

   chain = TlsGetCertChain()
   for k, v in pairs(chain) do
      -- v.length is length of data
      -- v.data is raw binary data of certificate
      cert = x509.new(v["data"], "DER")
      print(cert:text() .. "\n")
   end

18.2.5.4. TlsGetCertNotAfter

Get the Unix timestamp of end of validity of certificate.

Example:

function log (args)
    notafter = TlsGetCertNotAfter()
    if notafter < os.time() then
        -- expired certificate
    end
end

18.2.5.5. TlsGetCertNotBefore

Get the Unix timestamp of beginning of validity of certificate.

Example:

function log (args)
    notbefore = TlsGetCertNotBefore()
    if notbefore > os.time() then
        -- not yet valid certificate
    end
end

18.2.5.6. TlsGetCertSerial

Get TLS certificate serial number through TlsGetCertSerial.

Example:

function log (args)
    serial = TlsGetCertSerial()
    if serial then
        -- do something
    end
end

18.2.5.7. TlsGetSNI

Get the Server name Indication from a TLS connection.

Example:

function log (args)
    asked_domain = TlsGetSNI()
    if string.find(asked_domain, "badguys") then
        -- ok connection to bad guys let's do something
    end
end

18.2.6. Streaming Data

Streaming data can currently log out reassembled TCP data and normalized HTTP data. The script will be invoked for each consecutive data chunk.

In case of TCP reassembled data, all possible overlaps are removed according to the host OS settings.

function init (args)
    local needs = {}
    needs["type"] = "streaming"
    needs["filter"] = "tcp"
    return needs
end

In case of HTTP body data, the bodies are unzipped and dechunked if applicable.

function init (args)
    local needs = {}
    needs["type"] = "streaming"
    needs["protocol"] = "http"
    return needs
end

18.2.6.1. SCStreamingBuffer

function log(args)
    -- sb_ts and sb_tc are bools indicating the direction of the data
    data, sb_open, sb_close, sb_ts, sb_tc = SCStreamingBuffer()
    if sb_ts then
      print("->")
    else
      print("<-")
    end
    hex_dump(data)
end

18.2.7. Flow variables

It is possible to access, define and modify Flow variables from Lua. To do so, you must use the functions described in this section and declare the counter in init function:

function init(args)
    local needs = {}
    needs["tls"] tostring(true)
    needs["flowint"] = {"tls-cnt"}
    return needs
end

Here we define a tls-cnt Flowint that can now be used in output or in a signature via dedicated functions. The access to the Flow variable is done by index so in our case we need to use 0.

function match(args)
    a = SCFlowintGet(0);
    if a then
        SCFlowintSet(0, a + 1)
    else
        SCFlowintSet(0, 1)
    end

18.2.7.1. SCFlowintGet

Get the Flowint at index given by the parameter.

18.2.7.2. SCFlowintSet

Set the Flowint at index given by the first parameter. The second parameter is the value.

18.2.7.3. SCFlowintIncr

Increment Flowint at index given by the first parameter.

18.2.7.4. SCFlowintDecr

Decrement Flowint at index given by the first parameter.

18.2.8. Misc

18.2.8.1. SCThreadInfo

tid, tname, tgroup = SCThreadInfo()

It gives: tid (integer), tname (string), tgroup (string)

18.2.8.2. SCLogError, SCLogWarning, SCLogNotice, SCLogInfo, SCLogDebug

Print a message. It will go into the outputs defined in the yaml. Whether it will be printed depends on the log level.

Example:

SCLogError("some error message")

18.2.8.3. SCLogPath

Expose the log path.

name = "fast_lua.log"
function setup (args)
    filename = SCLogPath() .. "/" .. name
    file = assert(io.open(filename, "a"))
end

18.2.8.4. SCByteVarGet

Get the ByteVar at index given by the parameter. These variables are defined by byte_extract or byte_math in Suricata rules. Only callable from match scripts.

function init(args)
    local needs = {}
    needs["bytevar"] = {"var1", "var2"}
    return needs
end

Here we define a register that we will be using variables var1 and var2. The access to the Byte variables is done by index.

function match(args)
    var1 = SCByteVarGet(0)
    var2 = SCByteVarGet(1)