From cd69955d7fca991d0ffc615f6ee7dce9dd20a3c5 Mon Sep 17 00:00:00 2001
From: Juliana Fajardini <jufajardini@oisf.net>
Date: Wed, 26 Mar 2025 16:08:12 -0700
Subject: [PATCH] doc/userguide: add lua flowlib docs

Task #7489
---
 doc/userguide/lua/libs/flowlib.rst | 148 +++++++++++++++++++++++++++++
 doc/userguide/lua/libs/index.rst   |   1 +
 2 files changed, 149 insertions(+)
 create mode 100644 doc/userguide/lua/libs/flowlib.rst

diff --git a/doc/userguide/lua/libs/flowlib.rst b/doc/userguide/lua/libs/flowlib.rst
new file mode 100644
index 0000000000..33e95a15b9
--- /dev/null
+++ b/doc/userguide/lua/libs/flowlib.rst
@@ -0,0 +1,148 @@
+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 .
diff --git a/doc/userguide/lua/libs/index.rst b/doc/userguide/lua/libs/index.rst
index e5a12e5d7b..e4e52228b1 100644
--- a/doc/userguide/lua/libs/index.rst
+++ b/doc/userguide/lua/libs/index.rst
@@ -10,5 +10,6 @@ environment without access to additional modules.
 
    base64
    dns
+   flowlib
    hashlib
    packetlib
-- 
2.47.2