]>
Commit | Line | Data |
---|---|---|
0c4bf2d3 EL |
1 | .. _lua-output: |
2 | ||
b252b0d8 JI |
3 | Lua Output |
4 | ========== | |
5 | ||
3307f7a9 RS |
6 | Suricata offers the possibility to get more detailed output on specific kinds of |
7 | network traffic via pluggable lua scripts. You can write these scripts yourself and only need to | |
8 | define four hook functions. | |
9 | ||
10 | For lua output scripts suricata offers a wide range of lua functions. | |
11 | They all return information on specific engine internals and aspects of the network traffic. | |
12 | They are described in the following sections, grouped by the event/traffic type. | |
7c636d25 | 13 | But let's start with an example explaining the four hook functions, and how to make |
3307f7a9 | 14 | suricata load a lua output script. |
b252b0d8 JI |
15 | |
16 | Script structure | |
17 | ---------------- | |
18 | ||
3307f7a9 | 19 | A lua output script needs to define 4 hook functions: init(), setup(), log(), deinit() |
b252b0d8 | 20 | |
3307f7a9 RS |
21 | * init() -- registers where the script hooks into the output engine |
22 | * setup() -- does per output thread setup | |
23 | * log() -- logging function | |
24 | * deinit() -- clean up function | |
b252b0d8 JI |
25 | |
26 | Example: | |
27 | ||
28 | :: | |
29 | ||
30 | function init (args) | |
31 | local needs = {} | |
32 | needs["protocol"] = "http" | |
33 | return needs | |
34 | end | |
35 | ||
36 | function setup (args) | |
37 | filename = SCLogPath() .. "/" .. name | |
38 | file = assert(io.open(filename, "a")) | |
39 | SCLogInfo("HTTP Log Filename " .. filename) | |
40 | http = 0 | |
41 | end | |
42 | ||
43 | function log(args) | |
44 | http_uri = HttpGetRequestUriRaw() | |
45 | if http_uri == nil then | |
46 | http_uri = "<unknown>" | |
47 | end | |
48 | http_uri = string.gsub(http_uri, "%c", ".") | |
49 | ||
50 | http_host = HttpGetRequestHost() | |
51 | if http_host == nil then | |
52 | http_host = "<hostname unknown>" | |
53 | end | |
54 | http_host = string.gsub(http_host, "%c", ".") | |
55 | ||
56 | http_ua = HttpGetRequestHeader("User-Agent") | |
57 | if http_ua == nil then | |
58 | http_ua = "<useragent unknown>" | |
59 | end | |
60 | http_ua = string.gsub(http_ua, "%g", ".") | |
61 | ||
dc07c1fe RS |
62 | timestring = SCPacketTimeString() |
63 | ip_version, src_ip, dst_ip, protocol, src_port, dst_port = SCFlowTuple() | |
b252b0d8 | 64 | |
dc07c1fe RS |
65 | file:write (timestring .. " " .. http_host .. " [**] " .. http_uri .. " [**] " .. |
66 | http_ua .. " [**] " .. src_ip .. ":" .. src_port .. " -> " .. | |
67 | dst_ip .. ":" .. dst_port .. "\n") | |
b252b0d8 JI |
68 | file:flush() |
69 | ||
70 | http = http + 1 | |
71 | end | |
72 | ||
73 | function deinit (args) | |
74 | SCLogInfo ("HTTP transactions logged: " .. http); | |
75 | file:close(file) | |
76 | end | |
77 | ||
78 | YAML | |
79 | ---- | |
80 | ||
81 | To enable the lua output, add the 'lua' output and add one or more | |
82 | scripts like so: | |
83 | ||
84 | :: | |
85 | ||
86 | outputs: | |
87 | - lua: | |
88 | enabled: yes | |
89 | scripts-dir: /etc/suricata/lua-output/ | |
90 | scripts: | |
91 | - tcp-data.lua | |
92 | - flow.lua | |
93 | ||
94 | The scripts-dir option is optional. It makes Suricata load the scripts | |
95 | from this directory. Otherwise scripts will be loaded from the current | |
96 | workdir. | |
97 | ||
1e8959b4 | 98 | Developing lua output script |
0c4bf2d3 | 99 | ----------------------------- |
b252b0d8 | 100 | |
0c4bf2d3 | 101 | You can use functions described in :ref:`Lua Functions <lua-functions>` |