.. _lua-output:

Lua Output

Suricata offers the possibility to get more detailed output on specific kinds of network traffic via pluggable lua scripts. You can write these scripts yourself and only need to define four hook functions.

For lua output scripts suricata offers a wide range of lua functions. They all return information on specific engine internals and aspects of the network traffic. They are described in the following sections, grouped by the event/traffic type. But let's start with an example explaining the four hook functions, and how to make suricata load a lua output script.

Script structure

A lua output script needs to define 4 hook functions: init(), setup(), log(), deinit()

• init() -- registers where the script hooks into the output engine
• setup() -- does per output thread setup
• log() -- logging function
• deinit() -- clean up function

Example:

::

local config = require("suricata.config") local logger = require("suricata.log") local http = require("suricata.http") local packet = require("suricata.packet") local flow = require("suricata.flow")

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

function setup (args) filename = config.log_path() .. "/" .. name file = assert(io.open(filename, "a")) logger.info("HTTP Log Filename " .. filename) http = 0 end

function log(args) local tx = http.get_tx()

  http_uri = tx:request_uri_raw()
  if http_uri == nil then
      http_uri = "<unknown>"
  end
  http_uri = string.gsub(http_uri, "%c", ".")

  http_host = tx:request_host()
  if http_host == nil then
      http_host = "<hostname unknown>"
  end
  http_host = string.gsub(http_host, "%c", ".")

  http_ua = tx:request_header("User-Agent")
  if http_ua == nil then
      http_ua = "<useragent unknown>"
  end
  http_ua = string.gsub(http_ua, "%g", ".")

  local p = packet.get()
  timestring = p:timestring_legacy()
  ip_version, src_ip, dst_ip, protocol, src_port, dst_port = p:tuple()

  file:write (timestring .. " " .. http_host .. " [**] " .. http_uri .. " [**] " ..
         http_ua .. " [**] " .. src_ip .. ":" .. src_port .. " -> " ..
         dst_ip .. ":" .. dst_port .. "\n")
  file:flush()

  http = http + 1

end

function deinit (args) logger.info ("HTTP transactions logged: " .. http); file:close(file) end

.. _lua-output-yaml:

YAML

To enable the lua output, add the 'lua' output and add one or more scripts like so:

::

outputs: - lua: enabled: yes scripts-dir: /etc/suricata/lua-output/

    # By default the Lua module search paths are empty. If you plan
    # to use external modules these paths will need to be set. The
    # examples below are likely suitable for finding modules
    # installed with a package manager on a 64 bit Linux system, but
    # may need tweaking.
    #path: "/usr/share/lua/5.4/?.lua;/usr/share/lua/5.4/?/init.lua;/usr/lib64/lua/5.4/?.lua;/usr/lib64/lua/5.4/?/init.lua;./?.lua;./?/init.lua"
    #cpath: "/usr/lib64/lua/5.4/?.so;/usr/lib64/lua/5.4/loadall.so;./?.so"

    scripts:
      - tcp-data.lua
      - flow.lua

The scripts-dir option is optional. It makes Suricata load the scripts from this directory. Otherwise scripts will be loaded from the current workdir.

Developing lua output script

You can use functions described in :ref:Lua Functions <lua-functions>