mirror of https://github.com/OISF/suricata
You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
149 lines
3.6 KiB
ReStructuredText
149 lines
3.6 KiB
ReStructuredText
Flow
|
|
----
|
|
|
|
Flows are exposed to Lua scripts with the ``suricata.flow``
|
|
library. To use it, the script must require it. For example::
|
|
|
|
local flow = require("suricata.flow")
|
|
|
|
Following are the functions currently available for acessing Flow details.
|
|
|
|
Initialization
|
|
~~~~~~~~~~~~~~
|
|
|
|
``get``
|
|
^^^^^^^
|
|
|
|
Init the flow for use in the script. The flow is the current one the engine is
|
|
processing. ::
|
|
|
|
f = flow.get()
|
|
|
|
Time
|
|
~~~~
|
|
|
|
``timestamps``
|
|
^^^^^^^^^^^^^^
|
|
|
|
Get timestamps of the first and the last packets from the flow, as seconds and
|
|
microseconds since `1970-01-01 00:00:00` UTC, returning 4 numbers::
|
|
|
|
f = flow.get()
|
|
local start_sec, start_usec, last_sec, last_usec = f:timestamps()
|
|
|
|
``timestring_legacy``
|
|
^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Get the timestamp of the first packet from the flow, as a string in the format:
|
|
`11/24/2009-18:57:25.179869`. This is the format used by `fast.log`, `http.log`
|
|
and other legacy outputs.
|
|
|
|
::
|
|
|
|
f = flow.get()
|
|
print f:timestring_legacy()
|
|
|
|
``timestring_iso8601``
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Get the timestamp of the first packet from the flow, as a string in the format:
|
|
`2015-10-06T15:16:43.136733+0000`. This is the format used by EVE outputs.
|
|
|
|
::
|
|
|
|
f = flow.get()
|
|
print f:timestring_iso8601()
|
|
|
|
Ports and Addresses
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
``tuple``
|
|
~~~~~~~~~
|
|
|
|
Using the `tuple` method, the IP version (4 or 6), src IP and dest IP (as
|
|
string), IP protocol (int), and ports (ints) are retrieved.
|
|
|
|
The protocol value comes from the IP header. See further
|
|
https://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml .
|
|
|
|
::
|
|
|
|
f = flow.get()
|
|
ipver, srcip, dstip, proto, sp, dp = f:tuple()
|
|
|
|
App Layer Protocols
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
``app_layer_proto``
|
|
^^^^^^^^^^^^^^^^^^^
|
|
|
|
Get `alproto` from the flow as a string. If an `alproto` is not (yet) known, it
|
|
returns "unknown".
|
|
|
|
Returns 5 values: <alproto>, <alproto_ts>, <alproto_tc>, <alproto_orig>,
|
|
<alproto_expect>.
|
|
|
|
Example::
|
|
|
|
f = flow.get()
|
|
alproto, alproto_ts, alproto_tc, alproto_orig, alproto_expect = f:app_layer_proto()
|
|
|
|
`orig` and `expect` are used when changing and upgrading protocols. In an SMTP
|
|
STARTTLS case, `orig` would normally be set to "smtp" and `expect` to "tls".
|
|
|
|
Misc
|
|
~~~~
|
|
|
|
``has_alerts``
|
|
^^^^^^^^^^^^^^
|
|
|
|
Returns `true` if the flow has alerts. ::
|
|
|
|
f = flow.get()
|
|
alerted = f:has_alerts()
|
|
|
|
``id``
|
|
^^^^^^
|
|
|
|
Get the flow id. Note that simply printing the ``id`` will likely result in
|
|
printing a scientific notation. To avoid that, simply do::
|
|
|
|
f = flow.get()
|
|
id = f:id()
|
|
id_str = string.format("%.0f", id)
|
|
print ("Flow ID: " .. id_str .."\n")
|
|
|
|
``stats``
|
|
^^^^^^^^^
|
|
|
|
Get the packet and byte counts (for both directions), as 4 numbers, per flow.
|
|
|
|
::
|
|
|
|
f = flow.get()
|
|
tscnt, tsbytes, tccnt, tcbytes = f:stats()
|
|
|
|
Example
|
|
~~~~~~~
|
|
|
|
A simple ``log`` function for a script to output Flow details if the flow
|
|
triggered an alert::
|
|
|
|
function log(args)
|
|
local f = flow.get()
|
|
ts = f:timestring_iso8601()
|
|
has_alerts = f:has_alerts()
|
|
ipver, srcip, dstip, proto, sp, dp = f:tuple()
|
|
alproto, alproto_ts, alproto_tc, alproto_orig, alproto_expect = f:app_layer_proto()
|
|
start_sec, start_usec, last_sec, last_usec = f:timestamps()
|
|
id = f:id()
|
|
|
|
if has_alerts then
|
|
file:write ("[**] Start time " .. ts .. " [**] -> alproto " .. alproto .. " [**] " .. proto .. " [**] alerted: true\n[**] First packet: " .. start_sec .." [**] Last packet: " .. last_sec .. " [**] Flow id: " .. id .. "\n")
|
|
file:flush()
|
|
end
|
|
end
|
|
|
|
For complete scripts using these and other lua functions, the Suricata-verify
|
|
can be a good resource: https://github.com/OISF/suricata-verify/tree/master/tests .
|