pcap: refactor delete-when-done to support non-alerts

Refactor pcap file deletion to use a single delete-when-done option
with three values instead of separate boolean options:
- false (default): No deletion
- true: Always delete files
- "non-alerts": Delete only files with no alerts

Also account for alerts produced by pseudo packets (flow timeout / shutdown flush):
- Introduce small capture hooks and invoke on pseudo-packet creation so the
  capture layer can retain references and observe alerts emitted after the last
  live packet
- Call the hook from both TmThreadDisableReceiveThreads and TmThreadDrainPacketThreads

Key changes:
- Replace should_delete/delete_non_alerts_only bools with enum
- Move alert counter from global to per-file PcapFileFileVars
- Relocate alert counting from PacketAlertFinalize to pcap module
- Ensure thread safety for both single and continuous pcap modes
- Add unit tests for configuration parsing and pseudo-packet alert path

The --pcap-file-delete command line option overrides YAML config
and forces "always delete" mode for backward compatibility.

Documentation updated to reflect the new three-value configuration.

Fixes OISF#7786

Author: Ofer Dagan

doc/userguide/capture-hardware/pcap-file.rst

@@ -15,6 +15,8 @@ Configuration
     checksum-checks: auto
     # buffer-size: 128 KiB
     # tenant-id: none
+    # Applies to file and directory. Options: false (no deletion), true (always delete),
+    #   "non-alerts" (delete only files with no alerts)
     # delete-when-done: false
     # recursive: false
     # continuous: false
@@ -85,9 +87,22 @@ Other options
 
 **delete-when-done**
 
-- If ``true``, Suricata deletes the PCAP file after processing.
-- The command-line option is
-  :ref:`--pcap-file-delete <cmdline-option-pcap-file-delete>`
+Controls when PCAP files are deleted after processing. Three values are supported:
+
+- ``false`` (default): Files are never deleted
+- ``true``: Files are always deleted after processing
+- ``"non-alerts"``: Files are deleted only if they didn't generate any alerts
+
+.. note::
+
+   The command-line option :ref:`--pcap-file-delete <cmdline-option-pcap-file-delete>`
+   overrides this configuration and forces "always delete" mode (``true``).
+
+.. warning::
+
+   When using ``"non-alerts"`` mode, file deletion is deferred until thread
+   cleanup to ensure alert counts are finalized. This may delay deletion
+   compared to other modes.
 
 **BPF filter**
 

doc/userguide/partials/options.rst

@@ -80,10 +80,23 @@
 
 .. option:: --pcap-file-delete
 
-   Used with the -r option to indicate that the mode should delete pcap files
-   after they have been processed. This is useful with pcap-file-continuous to
-   continuously feed files to a directory and have them cleaned up when done. If
-   this option is not set, pcap files will not be deleted after processing.
+   Used with the -r option to force deletion of pcap files after they have been
+   processed. This is useful with pcap-file-continuous to continuously feed files
+   to a directory and have them cleaned up when done.
+
+   **command-line vs Configuration**: This command-line option overrides the
+   ``pcap-file.delete-when-done`` configuration option in ``suricata.yaml`` and
+   forces "always delete" mode (equivalent to ``delete-when-done: true``).
+
+   **For more control**, use the ``pcap-file.delete-when-done`` configuration
+   option instead, which supports three values:
+
+   - ``false`` (default): No files are deleted
+   - ``true``: All files are deleted after processing
+   - ``"non-alerts"``: Only files that generated no alerts are deleted
+
+   If neither ``--pcap-file-delete`` nor ``delete-when-done`` is configured,
+   pcap files will not be deleted after processing.
 
 .. _cmdline-option-pcap-file-buffer-size:
 

src/Makefile.am

@@ -51,6 +51,7 @@ noinst_HEADERS = \
 	app-layer.h \
 	bindgen.h \
 	build-info.h \
+	capture-hooks.h \
 	conf-yaml-loader.h \
 	conf.h \
 	counters.h \
@@ -636,6 +637,7 @@ libsuricata_c_a_SOURCES = \
 	app-layer-ssl.c \
 	app-layer-tftp.c \
 	app-layer.c \
+	capture-hooks.c \
 	conf-yaml-loader.c \
 	conf.c \
 	counters.c \

src/capture-hooks.c

@@ -0,0 +1,65 @@
+/* Copyright (C) 2007-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.
+ */
+
+/**
+ * \file
+ * Lightweight indirection layer for capture-related callbacks.
+ *
+ * This module lets the capture implementation register small hooks that the
+ * generic engine can invoke without hard dependencies. Two hooks are used:
+ * - on-alerts: invoked when a packet produced alerts so capture can update
+ *   per-input stats (e.g., deciding if a pcap should be deleted or kept).
+ * - on-pseudo-created: invoked when the engine creates pseudo packets (e.g.,
+ *   flow timeout or shutdown flush). This allows capture to retain references
+ *   or track alert outcomes tied to those pseudo packets.
+ */
+
+#include "suricata-common.h"
+#include "capture-hooks.h"
+
+static CaptureOnPacketWithAlertsHook g_on_alerts_hook = NULL;
+static CaptureOnPseudoPacketCreatedHook g_on_pseudo_created_hook = NULL;
+
+void CaptureHooksSet(
+        CaptureOnPacketWithAlertsHook OnAlerts, CaptureOnPseudoPacketCreatedHook OnPseudoCreated)
+{
+    /* Allow re-setting the same hooks (e.g. during pcap file reload), but BUG_ON
+     * if overwriting with different ones without clearing. */
+    if (g_on_alerts_hook != NULL) {
+        BUG_ON(g_on_alerts_hook != OnAlerts);
+    }
+    if (g_on_pseudo_created_hook != NULL) {
+        BUG_ON(g_on_pseudo_created_hook != OnPseudoCreated);
+    }
+
+    g_on_alerts_hook = OnAlerts;
+    g_on_pseudo_created_hook = OnPseudoCreated;
+}
+
+void CaptureHooksOnPacketWithAlerts(const Packet *p)
+{
+    if (g_on_alerts_hook != NULL) {
+        g_on_alerts_hook(p);
+    }
+}
+
+void CaptureHooksOnPseudoPacketCreated(Packet *p)
+{
+    if (g_on_pseudo_created_hook != NULL) {
+        g_on_pseudo_created_hook(p);
+    }
+}

src/capture-hooks.h

@@ -0,0 +1,43 @@
+/* Copyright (C) 2007-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.
+ */
+
+/**
+ * \file capture-hooks.h
+ * Small hook interface for capture modules to react to events in the
+ * generic engine without creating circular dependencies.
+ */
+
+#ifndef SURICATA_CAPTURE_HOOKS_H
+#define SURICATA_CAPTURE_HOOKS_H
+
+#include "suricata-common.h"
+
+struct Packet_;
+typedef struct Packet_ Packet;
+
+typedef void (*CaptureOnPacketWithAlertsHook)(const Packet *p);
+typedef void (*CaptureOnPseudoPacketCreatedHook)(Packet *p);
+
+/* Register/clear hooks (called by capture implementations) */
+void CaptureHooksSet(
+        CaptureOnPacketWithAlertsHook OnAlerts, CaptureOnPseudoPacketCreatedHook OnPseudoCreated);
+
+/* Invoke hooks (called from generic code, safe if unset) */
+void CaptureHooksOnPacketWithAlerts(const Packet *p);
+void CaptureHooksOnPseudoPacketCreated(Packet *p);
+
+#endif /* SURICATA_CAPTURE_HOOKS_H */

src/detect-engine-alert.c

@@ -37,6 +37,7 @@
 #include "util-validate.h"
 
 #include "action-globals.h"
+#include "capture-hooks.h"
 
 /** tag signature we use for tag alerts */
 static Signature g_tag_signature;
@@ -582,6 +583,12 @@ static inline void PacketAlertFinalizeProcessQueue(
             p->flags |= PKT_FIRST_ALERTS;
         }
     }
+
+    /* Notify capture layer about packets with real alerts (not pass-only),
+     * so capture impl can update per-capture context (e.g. pcap-file alert counts). */
+    if (alerted) {
+        CaptureHooksOnPacketWithAlerts(p);
+    }
 }
 
 /**

src/runmode-unittests.c

@@ -116,6 +116,7 @@
 #include "decode-vntag.h"
 #include "decode-vxlan.h"
 #include "decode-pppoe.h"
+#include "source-pcap-file-helper.h"
 
 #include "output-json-stats.h"
 
@@ -212,6 +213,7 @@ static void RegisterUnittests(void)
     StreamingBufferRegisterTests();
     MacSetRegisterTests();
     FlowRateRegisterTests();
+    SourcePcapFileHelperRegisterTests();
 #ifdef OS_WIN32
     Win32SyscallRegisterTests();
 #endif