flow/output: log triggered exception policy - v1

doc/userguide/configuration/exception-policies.rst

@@ -59,6 +59,12 @@ It is possible to disable this default, by setting the exception policies'
 **In IDS mode**, setting ``auto`` mode actually means disabling the
 ``master-switch``, or ignoring the exception policies.
 
+.. note::
+
+    If no exception policy is enabled, Suricata will not log exception policy stats.
+
+.. _eps_settings:
+
 Specific settings
 ~~~~~~~~~~~~~~~~~
 
@@ -210,12 +216,52 @@ Notes:
    * Not valid means that Suricata will error out and won't start.
    * ``REJECT`` will make Suricata send a Reset-packet unreach error to the sender of the matching packet.
 
+.. _eps_output:
+
+Log Output
+----------
+
+.. _eps_flow_event:
+
+Flow Event
+~~~~~~~~~~
+
+When an Exception Policy is triggered, this will be indicated in the flow log
+event for the associated flow, also indicating which target triggered that, and
+what policy was applied. If no exception policy is triggered, that field won't
+be present in the logs.
+
+Note that this is true even if the policy is applied only to certain packets from
+a flow.
+
+In the log below, the flow triggered the ``midstream policy``, leading to Suricata
+applying the configured behavior for such scenario: *to pass the flow* (``pass_flow``)::
+
+  "flow": {
+    "pkts_toserver": 4,
+    "pkts_toclient": 5,
+    "bytes_toserver": 495,
+    "bytes_toclient": 351,
+    "start": "2016-07-13T22:42:07.199672+0000",
+    "end": "2016-07-13T22:42:07.573174+0000",
+    "age": 0,
+    "state": "new",
+    "reason": "shutdown",
+    "alerted": false,
+    "action": "pass",
+    "exception_policy_triggered": {
+      "target": "stream_midstream",
+      "policy": "pass_flow"
+    }
+  },
+
 .. _eps_stats:
 
 Available Stats
----------------
+~~~~~~~~~~~~~~~
 
-There are stats counters for each supported exception policy scenario:
+There are stats counters for each supported exception policy scenario that will
+be logged when exception policies are enabled:
 
 .. list-table:: **Exception Policy Stats Counters**
    :widths: 50 50
@@ -244,7 +290,7 @@ Stats for application layer errors are available in summarized form or per
 application layer protocol. As the latter is extremely verbose, by default
 Suricata logs only the summary. If any further investigation is needed, it
 is recommended to enable per-app-proto exception policy error counters
-temporarily (for :ref:`stats configuration<suricata_yaml_outputs>`).
+temporarily (for more, read :ref:`stats configuration<suricata_yaml_outputs>`).
 
 
 Command-line Options for Simulating Exceptions

doc/userguide/output/eve/eve-json-format.rst

@@ -1669,6 +1669,12 @@ Fields
 * "state": display state of the flow (include "new", "established", "closed", "bypassed")
 * "reason": mechanism that did trigger the end of the flow (include "timeout", "forced" and "shutdown")
 * "alerted": "true" or "false" depending if an alert has been seen on flow
+* "action": "pass" or "drop" depending if flow was PASS'ed or DROP'ed (no present if none)
+* "exception_policy_triggered.target": if an exception policy was triggered,
+  what setting exception led to this (cf. :ref:`Exception Policy - Specific
+  Settings<eps_settings>`).
+* "exception_policy_triggered.policy": if an exception policy was triggered,
+  what policy was applied (to the flow or to any packet(s) from it)
 
 Example ::
 
@@ -1689,7 +1695,12 @@ Example ::
     "bypass": "capture",
     "state": "bypassed",
     "reason": "timeout",
-    "alerted": false
+    "alerted": false,
+    "action": "pass",
+    "exception_policy_triggered": {
+      "target": "stream_midstream",
+      "policy": "pass_flow"
+    }
   }
 
 Event type: RDP

etc/schema.json

@@ -1872,6 +1872,20 @@
                 "end": {
                     "type": "string"
                 },
+                "exception_policy_triggered": {
+                    "description": "The exception policy triggered by the flow. Not logged if none was triggered",
+                    "type": "object",
+                    "properties": {
+                        "target": {
+                            "description": "What triggered the exception",
+                            "type": "string"
+                        },
+                        "policy": {
+                            "description": "Which exception policy was applied",
+                            "type": "string"
+                        }
+                    }
+                },
                 "pkts_toclient": {
                     "type": "integer"
                 },

src/app-layer-parser.c

@@ -1,4 +1,4 @@
-/* Copyright (C) 2007-2021 Open Information Security Foundation
+/* Copyright (C) 2007-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
@@ -153,6 +153,11 @@ static void AppLayerConfig(void)
     g_applayerparser_error_policy = ExceptionPolicyParse("app-layer.error-policy", true);
 }
 
+enum ExceptionPolicy AppLayerErrorGetExceptionPolicy(void)
+{
+    return g_applayerparser_error_policy;
+}
+
 static void AppLayerParserFramesFreeContainer(FramesContainer *frames)
 {
     if (frames != NULL) {

src/app-layer-parser.h

@@ -1,4 +1,4 @@
-/* Copyright (C) 2007-2020 Open Information Security Foundation
+/* Copyright (C) 2007-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
@@ -136,6 +136,8 @@ void AppLayerParserThreadCtxFree(AppLayerParserThreadCtx *tctx);
 int AppLayerParserConfParserEnabled(const char *ipproto,
                                     const char *alproto_name);
 
+enum ExceptionPolicy AppLayerErrorGetExceptionPolicy(void);
+
 /** \brief Prototype for parsing functions */
 typedef AppLayerResult (*AppLayerParserFPtr)(Flow *f, void *protocol_state,
         AppLayerParserState *pstate, StreamSlice stream_slice, void *local_storage);

src/flow.h

@@ -1,4 +1,4 @@
-/* Copyright (C) 2007-2024 Open Information Security Foundation
+/* Copyright (C) 2007-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
@@ -55,7 +55,8 @@ typedef struct AppLayerParserState_ AppLayerParserState;
 /** next packet in toclient direction will act on updated app-layer state */
 #define FLOW_TC_APP_UPDATE_NEXT BIT_U32(2)
 
-// vacancy bit 3
+/** if an exception policy was triggered, use this to log about that */
+#define FLOW_TRIGGERED_EXCEPTION_POLICY BIT_U32(3)
 
 // vacancy bit 4
 
@@ -480,6 +481,9 @@ typedef struct Flow_
      *  has been set. */
     const struct SigGroupHead_ *sgh_toserver;
 
+    /** which exception policy was applied, if any */
+    uint16_t applied_exception_policy;
+
     /* pointer to the var list */
     GenericVar *flowvar;
 

src/output-json-flow.c

@@ -1,4 +1,4 @@
-/* Copyright (C) 2007-2020 Open Information Security Foundation
+/* Copyright (C) 2007-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
@@ -50,6 +50,7 @@
 #include "stream-tcp.h"
 #include "stream-tcp-private.h"
 #include "flow-storage.h"
+#include "util-exception-policy.h"
 
 static JsonBuilder *CreateEveHeaderFromFlow(const Flow *f)
 {
@@ -280,6 +281,14 @@ static void EveFlowLogJSON(OutputJsonThreadCtx *aft, JsonBuilder *jb, Flow *f)
     } else if (f->flags & FLOW_ACTION_PASS) {
         JB_SET_STRING(jb, "action", "pass");
     }
+    if (f->flags & FLOW_TRIGGERED_EXCEPTION_POLICY) {
+        jb_open_object(jb, "exception_policy_triggered");
+        jb_set_string(jb, "target", ExceptionPolicyTargetFlagToString(f->applied_exception_policy));
+        jb_set_string(jb, "policy",
+                ExceptionPolicyEnumToString(
+                        ExceptionPolicyTargetPolicy(f->applied_exception_policy), true));
+        jb_close(jb);
+    }
 
     /* Close flow. */
     jb_close(jb);

src/stream-tcp.c

@@ -1,4 +1,4 @@
-/* Copyright (C) 2007-2024 Open Information Security Foundation
+/* Copyright (C) 2007-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
@@ -896,6 +896,21 @@ static void StreamTcpSsnMemcapExceptionPolicyStatsIncr(
     }
 }
 
+enum ExceptionPolicy StreamTcpSsnMemcapGetExceptionPolicy(void)
+{
+    return stream_config.ssn_memcap_policy;
+}
+
+enum ExceptionPolicy StreamTcpReassemblyMemcapGetExceptionPolicy(void)
+{
+    return stream_config.reassembly_memcap_policy;
+}
+
+enum ExceptionPolicy StreamMidstreamGetExceptionPolicy(void)
+{
+    return stream_config.midstream_policy;
+}
+
 /** \internal
  *  \brief The function is used to fetch a TCP session from the
  *         ssn_pool, when a TCP SYN is received.

src/stream-tcp.h

@@ -1,4 +1,4 @@
-/* Copyright (C) 2007-2024 Open Information Security Foundation
+/* Copyright (C) 2007-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
@@ -158,6 +158,10 @@ void StreamTcpDetectLogFlush(ThreadVars *tv, StreamTcpThread *stt, Flow *f, Pack
 const char *StreamTcpStateAsString(const enum TcpState);
 const char *StreamTcpSsnStateAsString(const TcpSession *ssn);
 
+enum ExceptionPolicy StreamTcpSsnMemcapGetExceptionPolicy(void);
+enum ExceptionPolicy StreamTcpReassemblyMemcapGetExceptionPolicy(void);
+enum ExceptionPolicy StreamMidstreamGetExceptionPolicy(void);
+
 /** ------- Inline functions: ------ */
 
 /**

src/util-exception-policy-types.h

@@ -40,6 +40,15 @@ enum ExceptionPolicy {
  * "tcp.reassembly_exception_policy.drop_packet" + 1 */
 #define EXCEPTION_POLICY_COUNTER_MAX_LEN 45
 
+/** exception policy flags */
+#define EXCEPTION_DEFRAG_MEMCAP     BIT_U16(1)
+#define EXCEPTION_SESSION_MEMCAP    BIT_U16(2)
+#define EXCEPTION_REASSEMBLY_MEMCAP BIT_U16(3)
+#define EXCEPTION_FLOW_MEMCAP       BIT_U16(4)
+#define EXCEPTION_MIDSTREAM         BIT_U16(5)
+#define EXCEPTION_APPLAYER_ERROR    BIT_U16(6)
+/** 6 - 15 free */
+
 typedef struct ExceptionPolicyCounters_ {
     /* Follows enum order */
     uint16_t eps_id[EXCEPTION_POLICY_MAX];

src/util-exception-policy.c

@@ -1,4 +1,4 @@
-/* Copyright (C) 2022-2024 Open Information Security Foundation
+/* Copyright (C) 2022-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
@@ -19,14 +19,18 @@
  * \file
  */
 
+#include "util-exception-policy.h"
 #include "suricata-common.h"
 #include "suricata.h"
 #include "packet.h"
-#include "util-exception-policy.h"
 #include "util-misc.h"
 #include "stream-tcp-reassemble.h"
 #include "action-globals.h"
 #include "conf.h"
+#include "flow.h"
+#include "stream-tcp.h"
+#include "defrag-hash.h"
+#include "app-layer-parser.h"
 
 enum ExceptionPolicy g_eps_master_switch = EXCEPTION_POLICY_NOT_SET;
 /** true if exception policy was defined in config */
@@ -61,14 +65,73 @@ void SetMasterExceptionPolicy(void)
     g_eps_master_switch = ExceptionPolicyParse("exception-policy", true);
 }
 
-static enum ExceptionPolicy GetMasterExceptionPolicy(void)
+enum ExceptionPolicy GetMasterExceptionPolicy(void)
 {
     return g_eps_master_switch;
 }
 
+static uint16_t ExceptionPolicyFlag(enum PacketDropReason drop_reason)
+{
+    switch (drop_reason) {
+        case PKT_DROP_REASON_DEFRAG_MEMCAP:
+            return EXCEPTION_DEFRAG_MEMCAP;
+        case PKT_DROP_REASON_STREAM_MEMCAP:
+            return EXCEPTION_SESSION_MEMCAP;
+        case PKT_DROP_REASON_STREAM_REASSEMBLY:
+            return EXCEPTION_REASSEMBLY_MEMCAP;
+        case PKT_DROP_REASON_FLOW_MEMCAP:
+            return EXCEPTION_FLOW_MEMCAP;
+        case PKT_DROP_REASON_STREAM_MIDSTREAM:
+            return EXCEPTION_MIDSTREAM;
+        case PKT_DROP_REASON_APPLAYER_ERROR:
+            return EXCEPTION_APPLAYER_ERROR;
+        default:
+            return BIT_U16(0);
+    }
+    return BIT_U16(0);
+}
+
+const char *ExceptionPolicyTargetFlagToString(uint16_t target_flag)
+{
+    if (target_flag & EXCEPTION_DEFRAG_MEMCAP)
+        return "defrag_memcap";
+    if (target_flag & EXCEPTION_SESSION_MEMCAP)
+        return "stream_memcap";
+    if (target_flag & EXCEPTION_REASSEMBLY_MEMCAP)
+        return "stream_reassembly_memcap";
+    if (target_flag & EXCEPTION_FLOW_MEMCAP)
+        return "flow_memcap";
+    if (target_flag & EXCEPTION_MIDSTREAM)
+        return "stream_midstream";
+    if (target_flag & EXCEPTION_APPLAYER_ERROR)
+        return "app_layer_error";
+    return "ignore";
+}
+
+enum ExceptionPolicy ExceptionPolicyTargetPolicy(uint16_t target_flag)
+{
+    if (target_flag & EXCEPTION_DEFRAG_MEMCAP)
+        return DefragGetMemcapExceptionPolicy();
+    if (target_flag & EXCEPTION_SESSION_MEMCAP)
+        return StreamTcpSsnMemcapGetExceptionPolicy();
+    if (target_flag & EXCEPTION_REASSEMBLY_MEMCAP)
+        return StreamTcpReassemblyMemcapGetExceptionPolicy();
+    if (target_flag & EXCEPTION_FLOW_MEMCAP)
+        return FlowGetMemcapExceptionPolicy();
+    if (target_flag & EXCEPTION_MIDSTREAM)
+        return StreamMidstreamGetExceptionPolicy();
+    if (target_flag & EXCEPTION_APPLAYER_ERROR)
+        return AppLayerErrorGetExceptionPolicy();
+    return EXCEPTION_POLICY_NOT_SET;
+}
+
 void ExceptionPolicyApply(Packet *p, enum ExceptionPolicy policy, enum PacketDropReason drop_reason)
 {
     SCLogDebug("start: pcap_cnt %" PRIu64 ", policy %u", p->pcap_cnt, policy);
+    if (p->flow) {
+        p->flow->flags |= FLOW_TRIGGERED_EXCEPTION_POLICY;
+        p->flow->applied_exception_policy |= ExceptionPolicyFlag(drop_reason);
+    }
     switch (policy) {
         case EXCEPTION_POLICY_AUTO:
             break;

src/util-exception-policy.h

@@ -1,4 +1,4 @@
-/* Copyright (C) 2022-2024 Open Information Security Foundation
+/* Copyright (C) 2022-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
@@ -26,7 +26,10 @@
 #include "util-exception-policy-types.h"
 
 const char *ExceptionPolicyEnumToString(enum ExceptionPolicy policy, bool is_json);
+const char *ExceptionPolicyTargetFlagToString(uint16_t target_flag);
+enum ExceptionPolicy ExceptionPolicyTargetPolicy(uint16_t target_flag);
 void SetMasterExceptionPolicy(void);
+enum ExceptionPolicy GetMasterExceptionPolicy(void);
 void ExceptionPolicyApply(
         Packet *p, enum ExceptionPolicy policy, enum PacketDropReason drop_reason);
 enum ExceptionPolicy ExceptionPolicyParse(const char *option, const bool support_flow);