From: Jason Ish <jason.ish@oisf.net>
Date: Wed, 29 Oct 2025 23:47:44 +0000 (-0600)
Subject: doc/devguide: document eve callback
X-Git-Tag: suricata-8.0.2~13
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F14242%2Fhead;p=thirdparty%2Fsuricata.git

doc/devguide: document eve callback

Document the callback for adding additional data to EVE.

Ticket: #4708
(cherry picked from commit cdd4ea0f1144d36cf9da4137b4c0faf030f71bb5)
---

diff --git a/doc/userguide/devguide/extending/index.rst b/doc/userguide/devguide/extending/index.rst
index 0505f1625b..e2d56bdf07 100644
--- a/doc/userguide/devguide/extending/index.rst
+++ b/doc/userguide/devguide/extending/index.rst
@@ -10,3 +10,4 @@ Extending Suricata
    detect/index.rst
    output/index.rst
    output/eve-filetypes.rst
+   output/eve-hooks.rst
diff --git a/doc/userguide/devguide/extending/output/eve-hooks.rst b/doc/userguide/devguide/extending/output/eve-hooks.rst
new file mode 100644
index 0000000000..f130f1e5fc
--- /dev/null
+++ b/doc/userguide/devguide/extending/output/eve-hooks.rst
@@ -0,0 +1,43 @@
+EVE Hooks
+#########
+
+The EVE output provides a callback for additional data to be added to
+an EVE record before it is written.
+
+It is important to note that it does not allow for modification of the
+EVE record due to the append only nature of Suricata's EVE output.
+
+Registration
+************
+
+Registering the callback is done with ``SCEveRegisterCallback``.
+
+.. literalinclude:: ../../../../../src/output-eve.h
+   :language: c
+   :start-at: /** \brief Register a callback for adding extra information to EVE
+   :end-at: );
+
+Callback
+********
+
+The callback function is provided with an open ``SCJsonBuilder``
+instance just before being closed out with a final ``}``. Additional
+fields can be added with the ``SCJsonBuilder`` API.
+
+.. literalinclude:: ../../../../../src/output-eve.h
+   :language: c
+   :start-at: /** \brief Function type for EVE callbacks
+   :end-at: );
+
+Example
+*******
+
+For a real-life example, see the ``ndpi`` plugin included in the
+Suricata source.
+
+The example demonstrates:
+
+- Registering an EVE callback during plugin initialization
+- Using thread-local storage to maintain state
+- Adding protocol-specific information to EVE records
+- Properly checking for NULL pointers before accessing data