plugins: add ja4t-stub example plugin

The plugin is enabled with --enable-ja4t-stub and has no
dependencies on external libraries.

Author: jasonish

configure.ac

@@ -2326,6 +2326,20 @@ fi
     fi
     AC_SUBST([ndpi_comment])
 
+# JA4T stub plugin (no library dependencies)
+    AC_ARG_ENABLE(ja4t-stub,
+           AS_HELP_STRING([--enable-ja4t-stub], [Enable JA4T stub plugin]),
+           [enable_ja4t_stub=$enableval],[enable_ja4t_stub=no])
+
+    if test "x$enable_ja4t_stub" = "xyes"; then
+        AM_CONDITIONAL([BUILD_JA4T_STUB], [true])
+        ja4t_stub_comment=""
+    else
+        AM_CONDITIONAL([BUILD_JA4T_STUB], [false])
+        ja4t_stub_comment="#"
+    fi
+    AC_SUBST([ja4t_stub_comment])
+
     AC_ARG_ENABLE(warnings,
            AS_HELP_STRING([--enable-warnings], [Enable supported C compiler warnings]),[enable_warnings=$enableval],[enable_warnings=no])
     AS_IF([test "x$enable_warnings" = "xyes"], [
@@ -2577,6 +2591,7 @@ AC_CONFIG_FILES(plugins/Makefile)
 AC_CONFIG_FILES(plugins/pfring/Makefile)
 AC_CONFIG_FILES(plugins/napatech/Makefile)
 AC_CONFIG_FILES(plugins/ndpi/Makefile)
+AC_CONFIG_FILES(plugins/ja4t-stub/Makefile)
 
 AC_OUTPUT
 
@@ -2635,6 +2650,7 @@ SURICATA_BUILD_CONF="Suricata Configuration:
 
 Plugins:
   nDPI:                                    ${enable_ndpi}
+  JA4T stub:                               ${enable_ja4t_stub}
 
 Development settings:
   Coccinelle / spatch:                     ${enable_coccinelle}

plugins/Makefile.am

@@ -11,3 +11,7 @@ endif
 if BUILD_NDPI
 SUBDIRS += ndpi
 endif
+
+if BUILD_JA4T_STUB
+SUBDIRS += ja4t-stub
+endif

plugins/ja4t-stub/Makefile.am

@@ -0,0 +1,12 @@
+pkglib_LTLIBRARIES = ja4t-stub.la
+
+ja4t_stub_la_LDFLAGS = -module -avoid-version -shared
+
+# Only required to find these headers when building plugins from the
+# source directory.
+ja4t_stub_la_CFLAGS = -I../../rust/gen -I../../rust/dist
+
+ja4t_stub_la_SOURCES = ja4t-stub.c
+
+install-exec-hook:
+	cd $(DESTDIR)$(pkglibdir) && $(RM) $(pkglib_LTLIBRARIES)

plugins/ja4t-stub/ja4t-stub.c

@@ -0,0 +1,339 @@
+/* Copyright (C) 2026 Open Information Security Foundation
+ *
+ * You can copy, redistribute or modify this Program under the terms of
+ * the GNU General Public License version 2 as published by the Free
+ * Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * version 2 along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+ * 02110-1301, USA.
+ */
+
+/*
+ * This is a stub/example plugin demonstrating Suricata callback APIs.
+ * It doesn't perform any real analysis but shows how to hook into:
+ * - Thread lifecycle callbacks
+ * - Flow lifecycle callbacks
+ * - EVE output callbacks
+ * - Detection/keyword registration
+ */
+
+#include "suricata-common.h"
+#include "suricata-plugin.h"
+
+#include "detect-engine-helper.h"
+#include "detect-parse.h"
+#include "flow-callbacks.h"
+#include "flow-storage.h"
+#include "output-eve.h"
+#include "thread-callbacks.h"
+#include "thread-storage.h"
+#include "util-debug.h"
+
+static ThreadStorageId thread_storage_id = { .id = -1 };
+static FlowStorageId flow_storage_id = { .id = -1 };
+static int ja4t_stub_keyword_id = -1;
+
+/* Per-thread context structure */
+struct Ja4tThreadContext {
+    uint64_t packet_count;
+};
+
+/* Per-flow context structure */
+struct Ja4tFlowContext {
+    uint64_t packets;
+    uint64_t bytes;
+};
+
+/* Detection keyword data structure */
+typedef struct DetectJa4tStubData_ {
+    uint32_t value;
+    bool negated;
+} DetectJa4tStubData;
+
+/* Free thread storage */
+static void ThreadStorageFree(void *ptr)
+{
+    SCLogDebug("Free'ing JA4T stub thread storage");
+    struct Ja4tThreadContext *context = ptr;
+    SCFree(context);
+}
+
+/* Free flow storage */
+static void FlowStorageFree(void *ptr)
+{
+    SCLogDebug("Free'ing JA4T stub flow storage");
+    struct Ja4tFlowContext *ctx = ptr;
+    SCFree(ctx);
+}
+
+/* Flow initialization callback - called when a new flow is created */
+static void OnFlowInit(ThreadVars *tv, Flow *f, const Packet *p, void *_data)
+{
+    struct Ja4tFlowContext *flowctx = SCCalloc(1, sizeof(*flowctx));
+    if (flowctx == NULL) {
+        FatalError("Failed to allocate JA4T stub flow context");
+    }
+
+    flowctx->packets = 0;
+    flowctx->bytes = 0;
+    FlowSetStorageById(f, flow_storage_id, flowctx);
+
+    SCLogDebug("JA4T stub: Flow initialized");
+}
+
+/* Flow update callback - called for each packet in a flow */
+static void OnFlowUpdate(ThreadVars *tv, Flow *f, Packet *p, void *_data)
+{
+    struct Ja4tFlowContext *flowctx = FlowGetStorageById(f, flow_storage_id);
+
+    if (flowctx == NULL) {
+        return;
+    }
+
+    /* Update flow statistics */
+    flowctx->packets++;
+    flowctx->bytes += GET_PKT_LEN(p);
+
+    SCLogDebug("JA4T stub: Flow update - packets=%" PRIu64 ", bytes=%" PRIu64, flowctx->packets,
+            flowctx->bytes);
+}
+
+/* Flow finish callback - called when a flow is destroyed */
+static void OnFlowFinish(ThreadVars *tv, Flow *f, void *_data)
+{
+    struct Ja4tFlowContext *flowctx = FlowGetStorageById(f, flow_storage_id);
+
+    if (flowctx != NULL) {
+        SCLogDebug("JA4T stub: Flow finished - total packets=%" PRIu64 ", total bytes=%" PRIu64,
+                flowctx->packets, flowctx->bytes);
+    }
+}
+
+/* Thread initialization callback - called when a thread starts */
+static void OnThreadInit(ThreadVars *tv, void *_data)
+{
+    struct Ja4tThreadContext *context = SCCalloc(1, sizeof(*context));
+    if (context == NULL) {
+        FatalError("Failed to allocate JA4T stub thread context");
+    }
+
+    context->packet_count = 0;
+    ThreadSetStorageById(tv, thread_storage_id, context);
+
+    SCLogDebug("JA4T stub: Thread initialized");
+}
+
+/* Detection keyword packet match callback */
+static int DetectJa4tStubPacketMatch(
+        DetectEngineThreadCtx *det_ctx, Packet *p, const Signature *s, const SigMatchCtx *ctx)
+{
+    const Flow *f = p->flow;
+    struct Ja4tFlowContext *flowctx = FlowGetStorageById(f, flow_storage_id);
+    const DetectJa4tStubData *data = (const DetectJa4tStubData *)ctx;
+
+    SCEnter();
+
+    if (f == NULL) {
+        SCLogDebug("packet %" PRIu64 ": no flow", PcapPacketCntGet(p));
+        SCReturnInt(0);
+    }
+
+    if (flowctx == NULL) {
+        SCReturnInt(0);
+    }
+
+    /* Example matching logic: match if packet count exceeds threshold */
+    bool r = (flowctx->packets >= data->value);
+    r = r ^ data->negated;
+
+    if (r) {
+        SCLogDebug("JA4T stub keyword match on packet_count >= %u", data->value);
+        SCReturnInt(1);
+    }
+
+    SCReturnInt(0);
+}
+
+/* Parse detection keyword arguments */
+static DetectJa4tStubData *DetectJa4tStubParse(const char *arg, bool negate)
+{
+    DetectJa4tStubData *data;
+    char *endptr;
+    unsigned long val;
+
+    /* Parse numeric argument */
+    val = strtoul(arg, &endptr, 10);
+    if (*endptr != '\0' || endptr == arg) {
+        SCLogError("invalid ja4t-stub value '%s'", arg);
+        return NULL;
+    }
+
+    data = SCMalloc(sizeof(DetectJa4tStubData));
+    if (unlikely(data == NULL))
+        return NULL;
+
+    data->value = (uint32_t)val;
+    data->negated = negate;
+
+    return data;
+}
+
+/* Check for conflicts in detection keyword usage */
+static bool Ja4tStubDataHasConflicts(const DetectJa4tStubData *us, const DetectJa4tStubData *them)
+{
+    /* Check for mix of negated and non-negated */
+    if (them->negated ^ us->negated)
+        return true;
+
+    /* Check for multiple non-negated */
+    if (!us->negated)
+        return true;
+
+    /* Check for duplicate */
+    if (us->value == them->value)
+        return true;
+
+    return false;
+}
+
+/* Setup detection keyword */
+static int DetectJa4tStubSetup(DetectEngineCtx *de_ctx, Signature *s, const char *arg)
+{
+    DetectJa4tStubData *data = DetectJa4tStubParse(arg, s->init_data->negated);
+    if (data == NULL)
+        goto error;
+
+    SigMatch *tsm = s->init_data->smlists[DETECT_SM_LIST_MATCH];
+    for (; tsm != NULL; tsm = tsm->next) {
+        if (tsm->type == ja4t_stub_keyword_id) {
+            const DetectJa4tStubData *them = (const DetectJa4tStubData *)tsm->ctx;
+
+            if (Ja4tStubDataHasConflicts(data, them)) {
+                SCLogError("can't mix positive ja4t-stub match with negated");
+                goto error;
+            }
+        }
+    }
+
+    if (SCSigMatchAppendSMToList(de_ctx, s, ja4t_stub_keyword_id, (SigMatchCtx *)data,
+                DETECT_SM_LIST_MATCH) == NULL) {
+        goto error;
+    }
+    return 0;
+
+error:
+    if (data != NULL)
+        SCFree(data);
+    return -1;
+}
+
+/* Free detection keyword data */
+static void DetectJa4tStubFree(DetectEngineCtx *de_ctx, void *ptr)
+{
+    SCFree(ptr);
+}
+
+/* EVE output callback - adds data to EVE JSON output */
+static void EveCallback(ThreadVars *tv, const Packet *p, Flow *f, SCJsonBuilder *jb, void *data)
+{
+    /* EVE callback requires a flow */
+    if (f == NULL) {
+        return;
+    }
+
+    struct Ja4tFlowContext *flowctx = FlowGetStorageById(f, flow_storage_id);
+
+    if (flowctx == NULL) {
+        return;
+    }
+
+    SCLogDebug("JA4T stub EVE callback: tv=%p, p=%p, f=%p", tv, p, f);
+
+    /* Open a JA4T stub object in the EVE output */
+    SCJbOpenObject(jb, "ja4t_stub");
+
+    /* Add flow statistics */
+    SCJbSetUint(jb, "packet_count", flowctx->packets);
+    SCJbSetUint(jb, "byte_count", flowctx->bytes);
+
+    /* Close the JA4T stub object */
+    SCJbClose(jb);
+}
+
+/* Initialize detection keyword */
+static void Ja4tStubInitKeyword(void)
+{
+    /* SCSigTableAppLiteElmt and SCDetectHelperKeywordRegister don't yet
+     * support all the fields required to register the keyword,
+     * missing the (packet) Match callback,
+     * so we'll just register with an empty keyword specifier to get
+     * the ID, then fill in the ID. */
+    ja4t_stub_keyword_id = SCDetectHelperNewKeywordId();
+    SCLogDebug("Registered new ja4t-stub keyword with ID %" PRIu32, ja4t_stub_keyword_id);
+
+    sigmatch_table[ja4t_stub_keyword_id].name = "ja4t-stub";
+    sigmatch_table[ja4t_stub_keyword_id].desc = "match on JA4T stub flow statistics";
+    sigmatch_table[ja4t_stub_keyword_id].url = "/rules/ja4t-stub.html";
+    sigmatch_table[ja4t_stub_keyword_id].Match = DetectJa4tStubPacketMatch;
+    sigmatch_table[ja4t_stub_keyword_id].Setup = DetectJa4tStubSetup;
+    sigmatch_table[ja4t_stub_keyword_id].Free = DetectJa4tStubFree;
+    sigmatch_table[ja4t_stub_keyword_id].flags =
+            (SIGMATCH_QUOTES_OPTIONAL | SIGMATCH_HANDLE_NEGATION);
+}
+
+/* Plugin initialization */
+static void Ja4tStubInit(void)
+{
+    SCLogNotice("Initializing JA4T stub plugin - example of Suricata callback APIs");
+
+    /* Register thread storage for per-thread data */
+    thread_storage_id = ThreadStorageRegister("ja4t_stub", sizeof(void *), NULL, ThreadStorageFree);
+    if (thread_storage_id.id < 0) {
+        FatalError("Failed to register JA4T stub thread storage");
+    }
+
+    /* Register flow storage for per-flow data */
+    flow_storage_id = FlowStorageRegister("ja4t_stub", sizeof(void *), NULL, FlowStorageFree);
+    if (flow_storage_id.id < 0) {
+        FatalError("Failed to register JA4T stub flow storage");
+    }
+
+    /* Register flow lifecycle callbacks */
+    SCFlowRegisterInitCallback(OnFlowInit, NULL);
+    SCFlowRegisterUpdateCallback(OnFlowUpdate, NULL);
+    SCFlowRegisterFinishCallback(OnFlowFinish, NULL);
+
+    /* Register thread init callback */
+    SCThreadRegisterInitCallback(OnThreadInit, NULL);
+
+    /* Register an EVE callback for JSON output */
+    SCEveRegisterCallback(EveCallback, NULL);
+
+    /* Register detection keyword */
+    Ja4tStubInitKeyword();
+
+    SCLogNotice("JA4T stub plugin initialized successfully");
+}
+
+/* Plugin registration structure */
+const SCPlugin PluginRegistration = {
+    .version = SC_API_VERSION,
+    .suricata_version = SC_PACKAGE_VERSION,
+    .name = "ja4t-stub",
+    .author = "Open Information Security Foundation",
+    .license = "GPLv2",
+    .Init = Ja4tStubInit,
+};
+
+/* Entry point for plugin loading */
+const SCPlugin *SCPluginRegister(void)
+{
+    return &PluginRegistration;
+}