WIP start of pkt hook

WIP packet: track hooks that this packet triggers

hooks: set flow_start hook in packet

detect: pack prefilter engine struct

For future expansion of the fields.

detect/prefilter: put pkt mask in struct

In preparation for adding more pkt fields.

WIP detect: implement pkt:flow_start hook

SQUASH detect flow start hook

src/decode.h

@@ -511,8 +511,13 @@ typedef struct Packet_
     /* coccinelle: Packet:flowflags:FLOW_PKT_ */
 
     uint8_t app_update_direction; // enum StreamUpdateDir
+
+    /** sig mask flags this packet has, used in signature matching */
     SignatureMask sig_mask;
 
+    /** bit flags of SignatureHookPkt values this packet should trigger */
+    uint16_t pkt_hooks;
+
     /* Pkt Flags */
     uint32_t flags;
 

src/detect-engine-build.c

@@ -208,6 +208,10 @@ static bool SignatureInspectsBuffers(const Signature *s)
  */
 int SignatureIsIPOnly(DetectEngineCtx *de_ctx, const Signature *s)
 {
+    /* explicit hook means no IP-only */
+    if (s->init_data->hook.type != SIGNATURE_HOOK_TYPE_NOT_SET)
+        return 0;
+
     if (s->alproto != ALPROTO_UNKNOWN)
         return 0;
 
@@ -276,6 +280,10 @@ int SignatureIsIPOnly(DetectEngineCtx *de_ctx, const Signature *s)
  */
 static int SignatureIsPDOnly(const DetectEngineCtx *de_ctx, const Signature *s)
 {
+    /* explicit hook means no PD-only */
+    if (s->init_data->hook.type != SIGNATURE_HOOK_TYPE_NOT_SET)
+        return 0;
+
     if (s->alproto != ALPROTO_UNKNOWN)
         return 0;
 
@@ -354,6 +362,10 @@ static int SignatureIsInspectingPayload(DetectEngineCtx *de_ctx, const Signature
  */
 static int SignatureIsDEOnly(DetectEngineCtx *de_ctx, const Signature *s)
 {
+    /* explicit hook means no DE-only */
+    if (s->init_data->hook.type != SIGNATURE_HOOK_TYPE_NOT_SET)
+        SCReturnInt(0);
+
     if (s->alproto != ALPROTO_UNKNOWN) {
         SCReturnInt(0);
     }

src/detect-engine-prefilter-common.c

@@ -142,8 +142,9 @@ static int SetupEngineForPacketHeader(DetectEngineCtx *de_ctx, SigGroupHead *sgh
     SCLogDebug("%s: ctx %p extra type %u extra value %u, sig cnt %u",
             sigmatch_table[sm_type].name, ctx, ctx->type, ctx->value,
             ctx->sigs_cnt);
-    PrefilterAppendEngine(
-            de_ctx, sgh, Match, mask, ctx, PrefilterPacketHeaderFree, sigmatch_table[sm_type].name);
+    enum SignatureHookPkt hook = SIGNATURE_HOOK_PKT_NOT_SET; // TODO review
+    PrefilterAppendEngine(de_ctx, sgh, Match, mask, hook, ctx, PrefilterPacketHeaderFree,
+            sigmatch_table[sm_type].name);
     return 0;
 }
 
@@ -245,7 +246,8 @@ static int SetupEngineForPacketHeaderPrefilterPacketU8HashCtx(DetectEngineCtx *d
     }
 
     if (cnt) {
-        PrefilterAppendEngine(de_ctx, sgh, Match, mask, ctx, PrefilterPacketU8HashCtxFree,
+        enum SignatureHookPkt hook = SIGNATURE_HOOK_PKT_NOT_SET; // TODO review
+        PrefilterAppendEngine(de_ctx, sgh, Match, mask, hook, ctx, PrefilterPacketU8HashCtxFree,
                 sigmatch_table[sm_type].name);
     } else {
         PrefilterPacketU8HashCtxFree(ctx);

src/detect-engine-prefilter.c

@@ -1,4 +1,4 @@
-/* Copyright (C) 2016-2021 Open Information Security Foundation
+/* Copyright (C) 2016-2025 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
@@ -168,7 +168,12 @@ void Prefilter(DetectEngineThreadCtx *det_ctx, const SigGroupHead *sgh, Packet *
         /* run packet engines */
         PrefilterEngine *engine = sgh->pkt_engines;
         do {
-            if ((engine->ctx.pkt_mask & mask) == engine->ctx.pkt_mask) {
+            /* run engine if:
+             * mask matches
+             * no hook is used OR hook matches
+             */
+            if (((engine->ctx.pkt.mask & mask) == engine->ctx.pkt.mask) &&
+                    (engine->ctx.pkt.hook == 0 || (p->pkt_hooks & BIT_U16(engine->ctx.pkt.hook)))) {
                 PREFILTER_PROFILING_START(det_ctx);
                 engine->cb.Prefilter(det_ctx, p, engine->pectx);
                 PREFILTER_PROFILING_END(det_ctx, engine->gid);
@@ -211,7 +216,8 @@ void Prefilter(DetectEngineThreadCtx *det_ctx, const SigGroupHead *sgh, Packet *
 }
 
 int PrefilterAppendEngine(DetectEngineCtx *de_ctx, SigGroupHead *sgh, PrefilterPktFn PrefilterFunc,
-        SignatureMask mask, void *pectx, void (*FreeFunc)(void *pectx), const char *name)
+        SignatureMask mask, enum SignatureHookPkt hook, void *pectx, void (*FreeFunc)(void *pectx),
+        const char *name)
 {
     if (sgh == NULL || PrefilterFunc == NULL || pectx == NULL)
         return -1;
@@ -221,10 +227,14 @@ int PrefilterAppendEngine(DetectEngineCtx *de_ctx, SigGroupHead *sgh, PrefilterP
         return -1;
     memset(e, 0x00, sizeof(*e));
 
+    // TODO right now we represent the hook in a u8 in the prefilter engine for space reasons.
+    BUG_ON(hook >= 8);
+
     e->Prefilter = PrefilterFunc;
     e->pectx = pectx;
     e->Free = FreeFunc;
     e->pkt_mask = mask;
+    e->pkt_hook = hook;
 
     if (sgh->init->pkt_engines == NULL) {
         sgh->init->pkt_engines = e;
@@ -535,6 +545,14 @@ static void PrefilterPktNonPF(DetectEngineThreadCtx *det_ctx, Packet *p, const v
     }
 }
 
+static void PrefilterPktNonPFHookFlowStart(
+        DetectEngineThreadCtx *det_ctx, Packet *p, const void *pectx)
+{
+    if (p->flowflags & (FLOW_PKT_TOSERVER_FIRST | FLOW_PKT_TOCLIENT_FIRST)) {
+        PrefilterPktNonPF(det_ctx, p, pectx);
+    }
+}
+
 /** \internal
  *  \brief engine to select the non-prefilter rules for frames
  *  Checks the alproto and type as well.
@@ -631,6 +649,17 @@ static int SetupNonPrefilter(DetectEngineCtx *de_ctx, SigGroupHead *sgh)
     }
     uint32_t frame_non_pf_array_size = 0;
 
+    struct PrefilterNonPFDataSig *pkt_hook_flow_start_non_pf_array =
+            SCCalloc(max_sids, sizeof(*pkt_hook_flow_start_non_pf_array));
+    if (pkt_hook_flow_start_non_pf_array == NULL) {
+        SCFree(pkt_non_pf_array);
+        SCFree(frame_non_pf_array);
+        return -1;
+    }
+    uint32_t pkt_hook_flow_start_non_pf_array_size = 0;
+    SignatureMask pkt_hook_flow_start_mask = 0;
+    bool pkt_hook_flow_start_mask_init = false;
+
     HashListTable *tx_engines_hash =
             HashListTableInit(256, TxNonPFHash, TxNonPFCompare, TxNonPFFree);
     if (tx_engines_hash == NULL) {
@@ -663,19 +692,56 @@ static int SetupNonPrefilter(DetectEngineCtx *de_ctx, SigGroupHead *sgh)
         Signature *s = sgh->init->match_array[sig];
         if (s == NULL)
             continue;
-        SCLogDebug("checking sid %u for non-prefilter", s->id);
+        SCLogNotice("checking sid %u for non-prefilter", s->id);
         if (s->init_data->mpm_sm != NULL && (s->flags & SIG_FLAG_MPM_NEG) == 0)
             continue;
         if (s->init_data->prefilter_sm != NULL)
             continue;
         if ((s->flags & (SIG_FLAG_PREFILTER | SIG_FLAG_MPM_NEG)) == SIG_FLAG_PREFILTER)
             continue;
-        SCLogDebug("setting up sid %u for non-prefilter", s->id);
+        SCLogNotice("setting up sid %u for non-prefilter", s->id);
 
         uint8_t frame_type = 0; /**< only a single type per rule */
         bool tx_non_pf = false;
         bool frame_non_pf = false;
         bool pkt_non_pf = false;
+
+        if (s->init_data->hook.type == SIGNATURE_HOOK_TYPE_PKT &&
+                s->init_data->hook.t.pkt.ph == SIGNATURE_HOOK_PKT_FLOW_START) {
+
+            /* for pkt non prefilter, we have some space in the structure,
+             * so we can squeeze another filter */
+            uint8_t type;
+            uint16_t value;
+            if ((s->flags & SIG_FLAG_DSIZE) && s->dsize_mode == DETECT_UINT_EQ) {
+                SCLogDebug("dsize extra match");
+                type = 2;
+                value = s->dsize_low;
+            } else if (s->dp != NULL && s->dp->next == NULL && s->dp->port == s->dp->port2) {
+                type = 1;
+                value = s->dp->port;
+            } else {
+                type = 0;
+                value = s->alproto;
+            }
+            pkt_hook_flow_start_non_pf_array[pkt_hook_flow_start_non_pf_array_size].sid = s->num;
+            pkt_hook_flow_start_non_pf_array[pkt_hook_flow_start_non_pf_array_size].value = value;
+            pkt_hook_flow_start_non_pf_array[pkt_hook_flow_start_non_pf_array_size].type = type;
+            pkt_hook_flow_start_non_pf_array[pkt_hook_flow_start_non_pf_array_size].pkt.sig_mask =
+                    s->mask;
+            pkt_hook_flow_start_non_pf_array_size++;
+
+            if (pkt_hook_flow_start_mask_init) {
+                pkt_hook_flow_start_mask &= s->mask;
+            } else {
+                pkt_hook_flow_start_mask = s->mask;
+                pkt_hook_flow_start_mask_init = true;
+            }
+
+            SCLogNotice("flow_start hook");
+            continue; // done for this sig
+        }
+
         for (uint32_t x = 0; x < s->init_data->buffer_index; x++) {
             const int list_id = s->init_data->buffers[x].id;
             const DetectBufferType *buf = DetectEngineBufferTypeGetById(de_ctx, list_id);
@@ -896,12 +962,32 @@ static int SetupNonPrefilter(DetectEngineCtx *de_ctx, SigGroupHead *sgh)
         data->size = pkt_non_pf_array_size;
         memcpy((uint8_t *)&data->array, pkt_non_pf_array,
                 pkt_non_pf_array_size * sizeof(data->array[0]));
-        if (PrefilterAppendEngine(de_ctx, sgh, PrefilterPktNonPF, pkt_mask, (void *)data,
+        enum SignatureHookPkt hook = SIGNATURE_HOOK_PKT_NOT_SET; // TODO review
+        if (PrefilterAppendEngine(de_ctx, sgh, PrefilterPktNonPF, pkt_mask, hook, (void *)data,
                     PrefilterNonPFDataFree, "packet:non_pf") < 0) {
             SCFree(data);
             goto error;
         }
     }
+    if (pkt_hook_flow_start_non_pf_array_size) {
+        struct PrefilterNonPFData *data = SCCalloc(
+                1, sizeof(*data) + pkt_hook_flow_start_non_pf_array_size * sizeof(data->array[0]));
+        if (data == NULL)
+            goto error;
+        data->size = pkt_hook_flow_start_non_pf_array_size;
+        memcpy((uint8_t *)&data->array, pkt_hook_flow_start_non_pf_array,
+                pkt_hook_flow_start_non_pf_array_size * sizeof(data->array[0]));
+        SCLogNotice("packet:flow_start:non_pf added with %u rules", data->size);
+        enum SignatureHookPkt hook = SIGNATURE_HOOK_PKT_FLOW_START;
+        if (PrefilterAppendEngine(de_ctx, sgh,
+                    PrefilterPktNonPFHookFlowStart, // TODO no longer needed to have a dedicated
+                                                    // callback
+                    pkt_hook_flow_start_mask, hook, (void *)data, PrefilterNonPFDataFree,
+                    "packet:flow_start:non_pf") < 0) {
+            SCFree(data);
+            goto error;
+        }
+    }
     if (frame_non_pf_array_size) {
         SCLogDebug("%u frame non-pf sigs", frame_non_pf_array_size);
         struct PrefilterNonPFData *data =
@@ -973,7 +1059,11 @@ int PrefilterSetupRuleGroup(DetectEngineCtx *de_ctx, SigGroupHead *sgh)
         for (el = sgh->init->pkt_engines ; el != NULL; el = el->next) {
             e->local_id = el->id;
             e->cb.Prefilter = el->Prefilter;
-            e->ctx.pkt_mask = el->pkt_mask;
+            e->ctx.pkt.mask = el->pkt_mask;
+            // TODO right now we represent the hook in a u8 in the prefilter engine for space
+            // reasons.
+            BUG_ON(el->pkt_hook >= 8);
+            e->ctx.pkt.hook = (uint8_t)el->pkt_hook;
             e->pectx = el->pectx;
             el->pectx = NULL; // e now owns the ctx
             e->gid = el->gid;
@@ -998,7 +1088,11 @@ int PrefilterSetupRuleGroup(DetectEngineCtx *de_ctx, SigGroupHead *sgh)
         for (el = sgh->init->payload_engines ; el != NULL; el = el->next) {
             e->local_id = el->id;
             e->cb.Prefilter = el->Prefilter;
-            e->ctx.pkt_mask = el->pkt_mask;
+            e->ctx.pkt.mask = el->pkt_mask;
+            // TODO right now we represent the hook in a u8 in the prefilter engine for space
+            // reasons.
+            BUG_ON(el->pkt_hook >= 8);
+            e->ctx.pkt.hook = (uint8_t)el->pkt_hook;
             e->pectx = el->pectx;
             el->pectx = NULL; // e now owns the ctx
             e->gid = el->gid;
@@ -1404,8 +1498,9 @@ int PrefilterGenericMpmPktRegister(DetectEngineCtx *de_ctx, SigGroupHead *sgh, M
     pectx->mpm_ctx = mpm_ctx;
     pectx->transforms = &mpm_reg->transforms;
 
+    enum SignatureHookPkt hook = SIGNATURE_HOOK_PKT_NOT_SET; // TODO review
     int r = PrefilterAppendEngine(
-            de_ctx, sgh, PrefilterMpmPkt, 0, pectx, PrefilterMpmPktFree, mpm_reg->pname);
+            de_ctx, sgh, PrefilterMpmPkt, 0, hook, pectx, PrefilterMpmPktFree, mpm_reg->pname);
     if (r != 0) {
         SCFree(pectx);
     }

src/detect-engine-prefilter.h

@@ -51,7 +51,8 @@ void Prefilter(DetectEngineThreadCtx *, const SigGroupHead *, Packet *p, const u
         const SignatureMask mask);
 
 int PrefilterAppendEngine(DetectEngineCtx *de_ctx, SigGroupHead *sgh, PrefilterPktFn PrefilterFunc,
-        SignatureMask mask, void *pectx, void (*FreeFunc)(void *pectx), const char *name);
+        SignatureMask mask, enum SignatureHookPkt hook, void *pectx, void (*FreeFunc)(void *pectx),
+        const char *name);
 int PrefilterAppendPayloadEngine(DetectEngineCtx *de_ctx, SigGroupHead *sgh,
         PrefilterPktFn PrefilterFunc, void *pectx, void (*FreeFunc)(void *pectx), const char *name);
 int PrefilterAppendTxEngine(DetectEngineCtx *de_ctx, SigGroupHead *sgh,

src/detect-parse.c

@@ -1186,12 +1186,61 @@ static const char *SignatureHookTypeToString(enum SignatureHookType t)
             return "not_set";
         case SIGNATURE_HOOK_TYPE_APP:
             return "app";
-            // case SIGNATURE_HOOK_TYPE_PKT:
-            //     return "pkt";
+        case SIGNATURE_HOOK_TYPE_PKT:
+            return "pkt";
     }
     return "unknown";
 }
 
+static enum SignatureHookPkt HookPktFromString(const char *str)
+{
+    if (strcmp(str, "flow_start") == 0) {
+        return SIGNATURE_HOOK_PKT_FLOW_START;
+    }
+    return SIGNATURE_HOOK_PKT_NOT_SET;
+}
+
+static const char *HookPktToString(const enum SignatureHookPkt ph)
+{
+    switch (ph) {
+        case SIGNATURE_HOOK_PKT_NOT_SET:
+            return "not set";
+        case SIGNATURE_HOOK_PKT_FLOW_START:
+            return "flow_start";
+    }
+    return "error";
+}
+
+static SignatureHook SetPktHook(const char *hook_str)
+{
+    SignatureHook h = {
+        .type = SIGNATURE_HOOK_TYPE_PKT,
+        .t.pkt.ph = HookPktFromString(hook_str),
+    };
+    return h;
+}
+
+/**
+ * \param proto_hook string of protocol and hook, e.g. dns:request_complete
+ */
+static int SigParseProtoHookPkt(Signature *s, const char *proto_hook, const char *p, const char *h)
+{
+    if (strcmp(h, "flow_start") == 0) {
+        s->init_data->hook = SetPktHook(h);
+        if (s->init_data->hook.t.pkt.ph == SIGNATURE_HOOK_PKT_NOT_SET) {
+            return -1;
+        }
+    } else {
+        SCLogError("unknown pkt hook %s", h);
+    }
+    // s->init_data->hook.sm_list = list;
+
+    SCLogNotice("protocol:%s hook:%s: type:%s parsed hook:%s", p, h,
+            SignatureHookTypeToString(s->init_data->hook.type),
+            HookPktToString(s->init_data->hook.t.pkt.ph));
+    return 0;
+}
+
 static SignatureHook SetAppHook(const AppProto alproto, int progress)
 {
     SignatureHook h = {
@@ -1307,6 +1356,13 @@ static int SigParseProto(Signature *s, const char *protostr)
                     p, p);
             SCReturnInt(-1);
         }
+    } else if (h != NULL) {
+        SCLogNotice("non-app-layer rule with %s:%s", p, h);
+
+        if (SigParseProtoHookPkt(s, protostr, p, h) < 0) {
+            SCLogError("protocol \"%s\" does not support hook \"%s\"", p, h);
+            SCReturnInt(-1);
+        }
     }
 
     /* if any of these flags are set they are set in a mutually exclusive
@@ -2477,6 +2533,14 @@ static Signature *SigInitHelper(DetectEngineCtx *de_ctx, const char *sigstr,
         }
     }
 
+    if (sig->init_data->hook.type == SIGNATURE_HOOK_TYPE_PKT) {
+        if (sig->init_data->hook.t.pkt.ph == SIGNATURE_HOOK_PKT_FLOW_START) {
+            if ((sig->flags & SIG_FLAG_TOSERVER) != 0) {
+                sig->init_data->init_flags |= SIG_FLAG_INIT_FLOW;
+            }
+        }
+    }
+
     if (!(sig->init_data->init_flags & SIG_FLAG_INIT_FLOW)) {
         if ((sig->flags & (SIG_FLAG_TOSERVER|SIG_FLAG_TOCLIENT)) == 0) {
             sig->flags |= SIG_FLAG_TOSERVER;