17.2. Lua functions
17.2.1. packet
Initialize with:
function init (args)
local needs = {}
needs["type"] = "packet"
return needs
end
17.2.1.1. SCPacketTimestamp
Get packets timestamp as 2 numbers: seconds & microseconds elapsed since 1970-01-01 00:00:00 UTC.
function log(args)
local sec, usec = SCPacketTimestamp()
end
17.2.1.2. SCPacketTimeString
Use SCPacketTimeString to get the packet's time string in the format:
11/24/2009-18:57:25.179869
function log(args)
ts = SCPacketTimeString()
17.2.1.3. SCPacketTuple
ipver, srcip, dstip, proto, sp, dp = SCPacketTuple()
17.2.1.4. SCPacketPayload
p = SCPacketPayload()
17.2.2. flow
function init (args)
local needs = {}
needs["type"] = "flow"
return needs
end
17.2.2.1. SCFlowTimestamps
Get timestamps (seconds and microseconds) of the first and the last packet from the flow.
startts, lastts = SCFlowTimestamps()
startts_s, lastts_s, startts_us, lastts_us = SCFlowTimestamps()
17.2.2.2. SCFlowTimeString
startts = SCFlowTimeString()
17.2.2.3. SCFlowTuple
ipver, srcip, dstip, proto, sp, dp = SCFlowTuple()
17.2.2.4. SCFlowAppLayerProto
Get alproto as a string from the flow. If a alproto is not (yet) known, it returns "unknown".
Example:
function log(args)
alproto = SCFlowAppLayerProto()
if alproto ~= nil then
print (alproto)
end
end
Returns 5 values: <alproto> <alproto_ts> <alproto_tc> <alproto_orig> <alproto_expect>
Orig and expect are used when changing and upgrading protocols. In a SMTP STARTTLS case, orig would normally be set to "smtp" and expect to "tls".
17.2.2.5. SCFlowHasAlerts
Returns true if flow has alerts.
Example:
function log(args)
has_alerts = SCFlowHasAlerts()
if has_alerts then
-- do something
end
end
17.2.2.6. SCFlowStats
Gets the packet and byte counts per flow.
tscnt, tsbytes, tccnt, tcbytes = SCFlowStats()
17.2.2.7. SCFlowId
Gets the flow id.
id = SCFlowId()
Note that simply printing 'id' will likely result in printing a scientific notation. To avoid that, simply do:
id = SCFlowId()
idstr = string.format("%.0f",id)
print ("Flow ID: " .. idstr .. "\n")
17.2.3. http
Init with:
function init (args)
local needs = {}
needs["protocol"] = "http"
return needs
end
17.2.3.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
17.2.3.2. HttpGetRequestHost
Get the host from libhtp's tx->request_hostname, 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
17.2.3.3. HttpGetRequestHeader
http_ua = HttpGetRequestHeader("User-Agent")
if http_ua == nil then
http_ua = "<useragent unknown>"
end
17.2.3.4. HttpGetResponseHeader
server = HttpGetResponseHeader("Server");
print ("Server: " .. server);
17.2.3.5. HttpGetRequestLine
rl = HttpGetRequestLine();
print ("Request Line: " .. rl);
17.2.3.6. HttpGetResponseLine
rsl = HttpGetResponseLine();
print ("Response Line: " .. rsl);
17.2.3.7. HttpGetRawRequestHeaders
rh = HttpGetRawRequestHeaders();
print ("Raw Request Headers: " .. rh);
17.2.3.8. HttpGetRawResponseHeaders
rh = HttpGetRawResponseHeaders();
print ("Raw Response Headers: " .. rh);
17.2.3.9. HttpGetRequestUriRaw
http_uri = HttpGetRequestUriRaw()
if http_uri == nil then
http_uri = "<unknown>"
end
17.2.3.10. HttpGetRequestUriNormalized
http_uri = HttpGetRequestUriNormalized()
if http_uri == nil then
http_uri = "<unknown>"
end
17.2.3.11. HttpGetRequestHeaders
a = HttpGetRequestHeaders();
for n, v in pairs(a) do
print(n,v)
end
17.2.3.12. HttpGetResponseHeaders
a = HttpGetResponseHeaders();
for n, v in pairs(a) do
print(n,v)
end
17.2.4. DNS
17.2.4.1. DnsGetQueries
dns_query = DnsGetQueries();
if dns_query ~= nil then
for n, t in pairs(dns_query) do
rrname = t["rrname"]
rrtype = t["type"]
print ("QUERY: " .. ts .. " " .. rrname .. " [**] " .. rrtype .. " [**] " ..
"TODO" .. " [**] " .. srcip .. ":" .. sp .. " -> " ..
dstip .. ":" .. dp)
end
end
returns a table of tables
17.2.4.2. DnsGetAnswers
dns_answers = DnsGetAnswers();
if dns_answers ~= nil then
for n, t in pairs(dns_answers) do
rrname = t["rrname"]
rrtype = t["type"]
ttl = t["ttl"]
print ("ANSWER: " .. ts .. " " .. rrname .. " [**] " .. rrtype .. " [**] " ..
ttl .. " [**] " .. srcip .. ":" .. sp .. " -> " ..
dstip .. ":" .. dp)
end
end
returns a table of tables
17.2.4.4. DnsGetRcode
rcode = DnsGetRcode();
if rcode == nil then
return 0
end
print (rcode)
returns a lua string with the error message, or nil
17.2.4.5. DnsGetRecursionDesired
if DnsGetRecursionDesired() == true then
print ("RECURSION DESIRED")
end
returns a bool
17.2.5. TLS
Initialize with:
function init (args)
local needs = {}
needs["protocol"] = "tls"
return needs
end
17.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
17.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
17.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
17.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
17.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
17.2.5.6. TlsGetCertSerial
Get TLS certificate serial number through TlsGetCertSerial.
Example:
function log (args)
serial = TlsGetCertSerial()
if serial then
-- do something
end
end
17.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 someting
end
end
17.2.6. JA3
JA3 must be enabled in the Suricata config file (set 'app-layer.protocols.tls.ja3-fingerprints' to 'yes').
Initialize with:
function init (args)
local needs = {}
needs["protocol"] = "tls"
return needs
end
17.2.6.1. Ja3GetHash
Get the JA3 hash (md5sum of JA3 string) through Ja3GetHash.
Example:
function log (args)
hash = Ja3GetHash()
if hash == nil then
return
end
end
17.2.6.2. Ja3GetString
Get the JA3 string through Ja3GetString.
Example:
function log (args)
str = Ja3GetString()
if str == nil then
return
end
end
17.2.6.3. Ja3SGetHash
Get the JA3S hash (md5sum of JA3S string) through JA3SGetHash.
Example:
function log (args)
hash = Ja3SGetHash()
if hash == nil then
return
end
end
17.2.6.4. JA3SGetString
Get the JA3S string through Ja3SGetString.
Example:
function log (args)
str = Ja3SGetString()
if str == nil then
return
end
end
17.2.7. SSH
Initialize with:
function init (args)
local needs = {}
needs["protocol"] = "ssh"
return needs
end
17.2.7.1. SshGetServerProtoVersion
Get SSH protocol version used by the server through SshGetServerProtoVersion.
Example:
function log (args)
version = SshGetServerProtoVersion()
if version == nil then
return 0
end
end
17.2.7.2. SshGetServerSoftwareVersion
Get SSH software used by the server through SshGetServerSoftwareVersion.
Example:
function log (args)
software = SshGetServerSoftwareVersion()
if software == nil then
return 0
end
end
17.2.7.3. SshGetClientProtoVersion
Get SSH protocol version used by the client through SshGetClientProtoVersion.
Example:
function log (args)
version = SshGetClientProtoVersion()
if version == nil then
return 0
end
end
17.2.7.4. SshGetClientSoftwareVersion
Get SSH software used by the client through SshGetClientSoftwareVersion.
Example:
function log (args)
software = SshGetClientSoftwareVersion()
if software == nil then
return 0
end
end
17.2.7.5. HasshGet
Get MD5 of hassh algorithms used by the client through HasshGet.
Example:
function log (args)
hassh = HasshGet()
if hassh == nil then
return 0
end
end
17.2.7.6. HasshGetString
Get hassh algorithms used by the client through HasshGetString.
Example:
function log (args)
hassh_string = HasshGetString()
if hassh == nil then
return 0
end
end
17.2.7.7. HasshServerGet
Get MD5 of hassh algorithms used by the server through HasshServerGet.
Example:
function log (args)
hassh_string = HasshServerGet()
if hassh == nil then
return 0
end
end
17.2.7.8. HasshServerGetString
Get hassh algorithms used by the server through HasshServerGetString.
Example:
function log (args)
hassh_string = HasshServerGetString()
if hassh == nil then
return 0
end
end
17.2.8. Files
To use the file logging API, the script's init() function needs to look like:
function init (args)
local needs = {}
needs['type'] = 'file'
return needs
end
17.2.8.1. SCFileInfo
fileid, txid, name, size, magic, md5, sha1, sha256 = SCFileInfo()
returns fileid (number), txid (number), name (string), size (number), magic (string), md5 in hex (string), sha1 (string), sha256 (string)
17.2.8.2. SCFileState
state, stored = SCFileState()
returns state (string), stored (bool)
17.2.9. Alerts
Alerts are a subset of the 'packet' logger:
function init (args)
local needs = {}
needs["type"] = "packet"
needs["filter"] = "alerts"
return needs
end
17.2.9.1. SCRuleIds
sid, rev, gid = SCRuleIds()
17.2.9.2. SCRuleMsg
msg = SCRuleMsg()
17.2.9.3. SCRuleClass
class, prio = SCRuleClass()
17.2.10. 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
17.2.10.1. SCStreamingBuffer
function log(args)
data = SCStreamingBuffer()
hex_dump(data)
end
17.2.11. 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
17.2.11.1. SCFlowintGet
Get the Flowint at index given by the parameter.
17.2.11.2. SCFlowintSet
Set the Flowint at index given by the first parameter. The second parameter is the value.
17.2.11.3. SCFlowintIncr
Increment Flowint at index given by the first parameter.
17.2.11.4. SCFlowintDecr
Decrement Flowint at index given by the first parameter.
17.2.11.5. SCFlowvarGet
Get the Flowvar at index given by the parameter.
17.2.11.6. SCFlowvarSet
Set a Flowvar. First parameter is the index, second is the data and third is the length of data.
You can use it to set string
function init (args)
local needs = {}
needs["http.request_headers"] = tostring(true)
needs["flowvar"] = {"cnt"}
return needs
end
function match(args)
a = SCFlowvarGet(0);
if a then
a = tostring(tonumber(a)+1)
SCFlowvarSet(0, a, #a)
else
a = tostring(1)
SCFlowvarSet(0, a, #a)
end
17.2.12. Misc
17.2.12.1. SCThreadInfo
tid, tname, tgroup = SCThreadInfo()
It gives: tid (integer), tname (string), tgroup (string)
17.2.12.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")
17.2.12.3. SCLogPath
Expose the log path.
name = "fast_lua.log"
function setup (args)
filename = SCLogPath() .. "/" .. name
file = assert(io.open(filename, "a"))
end