loghunter-cli 0.1.0.dev0__py3-none-any.whl

tests/test_duration_detector.py

@@ -0,0 +1,491 @@
+"""Tests for the duration detector.
+
+All IP addresses use RFC 5737 documentation space:
+  192.0.2.x, 198.51.100.x, 203.0.113.x
+"""
+
+from __future__ import annotations
+
+import io
+import unittest
+from datetime import datetime, timezone
+
+import pandas as pd
+
+from loghunter.common.finding import DetectorContext, Finding, RunSummary, Severity
+from loghunter.detectors.duration import (
+    DETECTOR_NAME,
+    STATUS,
+    _duration_str,
+    run,
+)
+from loghunter.outputs.text import TextHandler
+from loghunter.runner import discover_detectors
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+_NOW = datetime(2026, 5, 30, tzinfo=timezone.utc)
+_WINDOW = (_NOW, _NOW)
+
+
+def _ctx(
+    df: pd.DataFrame | None,
+    cfg: dict | None = None,
+) -> DetectorContext:
+    logs = {"conn*.log*": df} if df is not None else {}
+    return DetectorContext(
+        logs=logs,
+        config=cfg or {},
+        allowlist=None,
+        data_window=_WINDOW,
+    )
+
+
+def _conn_row(
+    src: str = "192.0.2.10",
+    dst: str = "198.51.100.20",
+    port: int = 443,
+    proto: str = "tcp",
+    duration: float = 7200.0,
+    ts: float = 1_779_750_000.0,
+    **kwargs,
+) -> dict:
+    row = {
+        "src": src, "dst": dst, "port": port, "proto": proto,
+        "duration": duration, "ts": ts,
+    }
+    row.update(kwargs)
+    return row
+
+
+def _minimal_finding() -> Finding:
+    return Finding(
+        detector="duration",
+        severity=Severity.MEDIUM,
+        title="192.0.2.10 → 198.51.100.20:443/tcp",
+        description="A long-lived connection.",
+        evidence={
+            "src": "192.0.2.10",
+            "dst": "198.51.100.20",
+            "port": 443,
+            "proto": "tcp",
+            "max_duration_seconds": 7200.0,
+            "max_duration_str": "2h 0m",
+            "connection_count": 1,
+            "total_bytes": None,
+            "avg_bytes_per_second": None,
+            "conn_states": [],
+            "first_seen": None,
+            "last_seen": None,
+        },
+        next_steps=["Review the connection."],
+        ts_generated=_NOW,
+        data_window=_WINDOW,
+    )
+
+
+# ── Tests ─────────────────────────────────────────────────────────────────────
+
+class DurationDetectorTests(unittest.TestCase):
+
+    # ── Discovery ─────────────────────────────────────────────────────────────
+
+    def test_duration_is_available_in_discover_detectors(self) -> None:
+        detectors = discover_detectors()
+        self.assertIn("duration", detectors)
+        self.assertEqual(getattr(detectors["duration"], "STATUS", None), "available")
+
+    def test_detector_name_and_status_constants(self) -> None:
+        self.assertEqual(DETECTOR_NAME, "duration")
+        self.assertEqual(STATUS, "available")
+
+    # ── Empty / missing input ─────────────────────────────────────────────────
+
+    def test_run_returns_empty_when_no_conn_key(self) -> None:
+        self.assertEqual(run(_ctx(None)), [])
+
+    def test_run_returns_empty_on_empty_dataframe(self) -> None:
+        empty = pd.DataFrame(columns=["src", "dst", "port", "proto", "ts", "duration"])
+        self.assertEqual(run(_ctx(empty)), [])
+
+    def test_run_returns_empty_when_duration_column_absent(self) -> None:
+        df = pd.DataFrame([{"src": "192.0.2.10", "dst": "198.51.100.20",
+                            "port": 443, "proto": "tcp", "ts": 1_779_750_000.0}])
+        self.assertEqual(run(_ctx(df)), [])
+
+    def test_run_returns_empty_when_all_below_threshold(self) -> None:
+        df = pd.DataFrame([_conn_row(duration=299.0)])
+        self.assertEqual(run(_ctx(df, {"min_duration_seconds": 300})), [])
+
+    def test_run_returns_empty_when_all_nan(self) -> None:
+        df = pd.DataFrame([_conn_row(duration=float("nan"))])
+        self.assertEqual(run(_ctx(df)), [])
+
+    def test_run_returns_empty_when_all_zero(self) -> None:
+        df = pd.DataFrame([_conn_row(duration=0.0)])
+        self.assertEqual(run(_ctx(df)), [])
+
+    def test_run_returns_empty_when_all_negative(self) -> None:
+        df = pd.DataFrame([_conn_row(duration=-10.0)])
+        self.assertEqual(run(_ctx(df)), [])
+
+    # ── Core detection ────────────────────────────────────────────────────────
+
+    def test_medium_severity_at_7200s(self) -> None:
+        df = pd.DataFrame([_conn_row(duration=7200.0)])
+        findings = run(_ctx(df))
+        self.assertEqual(len(findings), 1)
+        self.assertEqual(findings[0].severity, Severity.MEDIUM)
+
+    def test_high_severity_at_14400s(self) -> None:
+        df = pd.DataFrame([_conn_row(duration=14400.0)])
+        findings = run(_ctx(df))
+        self.assertEqual(len(findings), 1)
+        self.assertEqual(findings[0].severity, Severity.HIGH)
+
+    def test_high_severity_above_14400s(self) -> None:
+        df = pd.DataFrame([_conn_row(duration=86400.0)])
+        findings = run(_ctx(df))
+        self.assertEqual(len(findings), 1)
+        self.assertEqual(findings[0].severity, Severity.HIGH)
+
+    def test_low_severity_at_301s_emitted(self) -> None:
+        df = pd.DataFrame([_conn_row(duration=301.0)])
+        findings = run(_ctx(df, {"min_duration_seconds": 300}))
+        self.assertEqual(len(findings), 1)
+        self.assertEqual(findings[0].severity, Severity.LOW)
+
+    def test_exactly_at_threshold_is_detected(self) -> None:
+        df = pd.DataFrame([_conn_row(duration=1800.0)])
+        # 1800s is LOW (< 7200) — under W6 the result set is verbosity-invariant,
+        # so LOW always emits; the text handler is responsible for hiding LOW at
+        # level 0.
+        findings = run(_ctx(df))
+        self.assertEqual(len(findings), 1)
+
+    def test_just_below_threshold_not_detected(self) -> None:
+        df = pd.DataFrame([_conn_row(duration=1799.9)])
+        self.assertEqual(run(_ctx(df)), [])
+
+    def test_multiple_findings_sorted_descending_by_max_duration(self) -> None:
+        df = pd.DataFrame([
+            _conn_row(src="192.0.2.10", duration=7200.0),
+            _conn_row(src="192.0.2.11", duration=14400.0),
+            _conn_row(src="192.0.2.12", duration=9000.0),
+        ])
+        findings = run(_ctx(df))
+        self.assertEqual(len(findings), 3)
+        durations = [f.evidence["max_duration_seconds"] for f in findings]
+        self.assertEqual(durations, sorted(durations, reverse=True))
+        self.assertEqual(findings[0].evidence["src"], "192.0.2.11")
+
+    def test_zero_duration_excluded_even_if_column_present(self) -> None:
+        df = pd.DataFrame([
+            _conn_row(src="192.0.2.10", duration=0.0),
+            _conn_row(src="192.0.2.11", duration=7200.0),
+        ])
+        findings = run(_ctx(df))
+        self.assertEqual(len(findings), 1)
+        self.assertEqual(findings[0].evidence["src"], "192.0.2.11")
+
+    def test_non_numeric_duration_values_tolerated(self) -> None:
+        df = pd.DataFrame([
+            _conn_row(src="192.0.2.10", duration="bad"),
+            _conn_row(src="192.0.2.11", duration=7200.0),
+        ])
+        findings = run(_ctx(df))
+        self.assertEqual(len(findings), 1)
+        self.assertEqual(findings[0].evidence["src"], "192.0.2.11")
+
+    # ── Grouping behavior ─────────────────────────────────────────────────────
+
+    def test_grouping_collapses_same_flow(self) -> None:
+        # Three rows for the same (src, dst, port, proto) → one finding
+        df = pd.DataFrame([
+            _conn_row(duration=7200.0,  ts=1_779_750_000.0),
+            _conn_row(duration=9000.0,  ts=1_779_750_100.0),
+            _conn_row(duration=7800.0,  ts=1_779_750_200.0),
+        ])
+        findings = run(_ctx(df))
+        self.assertEqual(len(findings), 1)
+        self.assertEqual(findings[0].evidence["connection_count"], 3)
+        self.assertEqual(findings[0].evidence["max_duration_seconds"], 9000.0)
+
+    def test_floor_row_excluded_from_group(self) -> None:
+        # One row below the floor; only the two above it count
+        df = pd.DataFrame([
+            _conn_row(duration=7200.0),
+            _conn_row(duration=9000.0),
+            _conn_row(duration=500.0),   # below default 1800s floor
+        ])
+        findings = run(_ctx(df))
+        self.assertEqual(len(findings), 1)
+        self.assertEqual(findings[0].evidence["connection_count"], 2)
+        self.assertEqual(findings[0].evidence["max_duration_seconds"], 9000.0)
+
+    def test_two_flows_produce_two_findings(self) -> None:
+        df = pd.DataFrame([
+            _conn_row(src="192.0.2.10", dst="198.51.100.1", port=443,  duration=7200.0),
+            _conn_row(src="192.0.2.10", dst="198.51.100.2", port=443,  duration=14400.0),
+        ])
+        findings = run(_ctx(df))
+        self.assertEqual(len(findings), 2)
+
+    # ── LOW severity: result-set verbosity invariance (W6) ────────────────────
+
+    def test_low_always_emitted_result_set_invariant(self) -> None:
+        """W6: duration.run() emits LOW findings regardless of verbosity. The
+        result set is invariant across verbose levels; the text handler is the
+        sole authority on hiding LOW at level 0 (W2 pipeline step 1)."""
+        # 2000s is LOW (< 7200) but above the 1800s floor.
+        df = pd.DataFrame([_conn_row(duration=2000.0)])
+        findings = run(_ctx(df))
+        self.assertEqual(len(findings), 1)
+        self.assertEqual(findings[0].severity, Severity.LOW)
+
+    # ── Evidence fields ───────────────────────────────────────────────────────
+
+    def test_max_duration_seconds_is_rounded_float(self) -> None:
+        df = pd.DataFrame([_conn_row(duration=7200.123456)])
+        f = run(_ctx(df))[0]
+        self.assertEqual(f.evidence["max_duration_seconds"], 7200.1)
+
+    def test_max_duration_str_present_and_non_empty(self) -> None:
+        df = pd.DataFrame([_conn_row(duration=7200.0)])
+        f = run(_ctx(df))[0]
+        self.assertIsInstance(f.evidence["max_duration_str"], str)
+        self.assertTrue(f.evidence["max_duration_str"])
+
+    def test_src_dst_port_proto_present(self) -> None:
+        df = pd.DataFrame([_conn_row(
+            src="192.0.2.10", dst="198.51.100.20", port=443, proto="tcp", duration=7200.0
+        )])
+        f = run(_ctx(df))[0]
+        self.assertEqual(f.evidence["src"], "192.0.2.10")
+        self.assertEqual(f.evidence["dst"], "198.51.100.20")
+        self.assertEqual(f.evidence["port"], 443)
+        self.assertEqual(f.evidence["proto"], "tcp")
+
+    def test_avg_bps_none_when_bytes_null(self) -> None:
+        df = pd.DataFrame([_conn_row(duration=7200.0)])
+        f = run(_ctx(df))[0]
+        self.assertIsNone(f.evidence["avg_bytes_per_second"])
+
+    def test_avg_bps_computed_when_bytes_present(self) -> None:
+        df = pd.DataFrame([_conn_row(duration=7200.0, bytes=720000)])
+        f = run(_ctx(df))[0]
+        self.assertIsNotNone(f.evidence["avg_bytes_per_second"])
+        self.assertAlmostEqual(f.evidence["avg_bytes_per_second"], 100.0, places=1)
+
+    def test_avg_bps_from_max_duration_row(self) -> None:
+        # Row 1: max duration 9000s, bytes 90000 → bps 10.0
+        # Row 2: shorter duration 7200s, bytes 720000 (higher bytes, shorter duration)
+        # avg_bps must use the max-duration row: 90000 / 9000 = 10.0
+        df = pd.DataFrame([
+            _conn_row(duration=9000.0, bytes=90000),
+            _conn_row(duration=7200.0, bytes=720000),
+        ])
+        findings = run(_ctx(df))
+        self.assertEqual(len(findings), 1)
+        self.assertAlmostEqual(findings[0].evidence["avg_bytes_per_second"], 10.0, places=1)
+
+    def test_avg_bps_none_when_column_absent(self) -> None:
+        df = pd.DataFrame([_conn_row(duration=7200.0)])
+        self.assertNotIn("bytes", df.columns)
+        f = run(_ctx(df))[0]
+        self.assertIsNone(f.evidence["avg_bytes_per_second"])
+
+    def test_total_bytes_none_when_all_null(self) -> None:
+        df = pd.DataFrame([
+            _conn_row(duration=7200.0, bytes=None),
+            _conn_row(duration=7800.0, bytes=float("nan")),
+        ])
+        findings = run(_ctx(df))
+        self.assertIsNone(findings[0].evidence["total_bytes"])
+
+    def test_total_bytes_none_when_column_absent(self) -> None:
+        df = pd.DataFrame([_conn_row(duration=7200.0)])
+        self.assertNotIn("bytes", df.columns)
+        f = run(_ctx(df))[0]
+        self.assertIsNone(f.evidence["total_bytes"])
+
+    def test_conn_states_when_single_state_present(self) -> None:
+        df = pd.DataFrame([_conn_row(duration=7200.0, conn_state="SF")])
+        f = run(_ctx(df))[0]
+        self.assertEqual(f.evidence["conn_states"], ["SF"])
+
+    def test_conn_states_distinct_sorted(self) -> None:
+        # Repeated and null states — expect sorted unique non-null list
+        df = pd.DataFrame([
+            _conn_row(duration=8000.0, conn_state="SF"),
+            _conn_row(duration=7800.0, conn_state="RSTO"),
+            _conn_row(duration=7200.0, conn_state="SF"),    # duplicate
+            _conn_row(duration=7500.0, conn_state=None),    # null, excluded
+        ])
+        findings = run(_ctx(df))
+        self.assertEqual(findings[0].evidence["conn_states"], ["RSTO", "SF"])
+
+    def test_conn_states_empty_list_when_column_absent(self) -> None:
+        df = pd.DataFrame([_conn_row(duration=7200.0)])
+        self.assertNotIn("conn_state", df.columns)
+        f = run(_ctx(df))[0]
+        self.assertEqual(f.evidence["conn_states"], [])
+
+    # ── Finding contract ──────────────────────────────────────────────────────
+
+    def test_title_contains_src_and_dst_port(self) -> None:
+        df = pd.DataFrame([_conn_row(
+            src="192.0.2.10", dst="198.51.100.20", port=443, proto="tcp", duration=7200.0
+        )])
+        f = run(_ctx(df))[0]
+        self.assertIn("192.0.2.10", f.title)
+        self.assertIn("198.51.100.20", f.title)
+        self.assertIn("443", f.title)
+
+    def test_title_does_not_contain_duration_value(self) -> None:
+        df = pd.DataFrame([_conn_row(duration=7200.0)])
+        f = run(_ctx(df))[0]
+        self.assertNotIn("7200", f.title)
+        self.assertNotIn("2h", f.title)
+
+    def test_detector_field_is_duration(self) -> None:
+        df = pd.DataFrame([_conn_row(duration=7200.0)])
+        f = run(_ctx(df))[0]
+        self.assertEqual(f.detector, "duration")
+
+    def test_next_steps_non_empty(self) -> None:
+        df = pd.DataFrame([_conn_row(duration=7200.0)])
+        f = run(_ctx(df))[0]
+        self.assertIsInstance(f.next_steps, list)
+        self.assertGreater(len(f.next_steps), 0)
+
+    # ── _duration_str helper ──────────────────────────────────────────────────
+
+    def test_duration_str_seconds(self) -> None:
+        self.assertEqual(_duration_str(47.0), "47s")
+
+    def test_duration_str_minutes(self) -> None:
+        self.assertEqual(_duration_str(872.0), "14m 32s")
+
+    def test_duration_str_hours(self) -> None:
+        self.assertEqual(_duration_str(15780.0), "4h 23m")
+
+    def test_duration_str_days(self) -> None:
+        self.assertEqual(_duration_str(93600.0), "1d 2h")
+
+    # ── Text renderer ─────────────────────────────────────────────────────────
+
+    def test_render_duration_group_no_exception(self) -> None:
+        summary = RunSummary(
+            data_window=_WINDOW,
+            record_counts={"conn*.log*": 1},
+            data_size_bytes=0,
+            detectors_run=["duration"],
+            detectors_skipped={},
+        )
+        stream = io.StringIO()
+        handler = TextHandler(stream=stream, verbose_level=0)
+        handler.begin(summary)
+        handler.write([_minimal_finding()])
+        handler.end()
+        self.assertTrue(len(stream.getvalue()) > 0)
+
+    def test_render_output_contains_key_tokens(self) -> None:
+        df = pd.DataFrame([_conn_row(
+            src="192.0.2.10", dst="198.51.100.20", port=443, proto="tcp", duration=7200.0
+        )])
+        findings = run(_ctx(df))
+        summary = RunSummary(
+            data_window=_WINDOW, record_counts={}, data_size_bytes=0,
+            detectors_run=["duration"], detectors_skipped={},
+        )
+        stream = io.StringIO()
+        handler = TextHandler(stream=stream, verbose_level=0)
+        handler.begin(summary)
+        handler.write(findings)
+        handler.end()
+        output = stream.getvalue()
+        self.assertIn("192.0.2.10", output)
+        self.assertIn("198.51.100.20", output)
+        self.assertIn("2h 0m", output)
+
+    def test_verbose_mode_emits_evidence_and_next_steps(self) -> None:
+        summary = RunSummary(
+            data_window=_WINDOW, record_counts={}, data_size_bytes=0,
+            detectors_run=["duration"], detectors_skipped={},
+        )
+        stream = io.StringIO()
+        handler = TextHandler(stream=stream, verbose_level=1)
+        handler.begin(summary)
+        handler.write([_minimal_finding()])
+        handler.end()
+        output = stream.getvalue()
+        self.assertIn("evidence:", output)
+        self.assertIn("next steps:", output)
+        self.assertIn("data window:", output)
+
+    def test_render_conns_column_pluralization(self) -> None:
+        # Two rows with the same flow tuple → grouped → "2 conns"
+        df = pd.DataFrame([
+            _conn_row(duration=7200.0, ts=1_779_750_000.0),
+            _conn_row(duration=7800.0, ts=1_779_750_100.0),
+        ])
+        findings = run(_ctx(df))
+        self.assertEqual(len(findings), 1)
+        summary = RunSummary(
+            data_window=_WINDOW, record_counts={}, data_size_bytes=0,
+            detectors_run=["duration"], detectors_skipped={},
+        )
+        stream = io.StringIO()
+        handler = TextHandler(stream=stream, verbose_level=0)
+        handler.begin(summary)
+        handler.write(findings)
+        handler.end()
+        self.assertIn("conns", stream.getvalue())
+
+    def test_render_single_conn_uses_singular(self) -> None:
+        df = pd.DataFrame([_conn_row(duration=7200.0)])
+        findings = run(_ctx(df))
+        summary = RunSummary(
+            data_window=_WINDOW, record_counts={}, data_size_bytes=0,
+            detectors_run=["duration"], detectors_skipped={},
+        )
+        stream = io.StringIO()
+        handler = TextHandler(stream=stream, verbose_level=0)
+        handler.begin(summary)
+        handler.write(findings)
+        handler.end()
+        self.assertIn("1 conn", stream.getvalue())
+
+    def test_arrow_alignment_across_multiple_findings(self) -> None:
+        """All → arrows must appear at the same column offset."""
+        df = pd.DataFrame([
+            _conn_row(src="192.0.2.10",  dst="198.51.100.1",   port=443,   duration=14400.0),
+            _conn_row(src="192.0.2.200", dst="203.0.113.5",    port=22,    duration=7200.0),
+            _conn_row(src="192.0.2.1",   dst="198.51.100.200", port=9997,  duration=7201.0),
+        ])
+        findings = run(_ctx(df))
+        self.assertEqual(len(findings), 3)
+
+        summary = RunSummary(
+            data_window=_WINDOW, record_counts={}, data_size_bytes=0,
+            detectors_run=["duration"], detectors_skipped={},
+        )
+        stream = io.StringIO()
+        handler = TextHandler(stream=stream, verbose_level=0)
+        handler.begin(summary)
+        handler.write(findings)
+        handler.end()
+
+        output_lines = stream.getvalue().splitlines()
+        finding_lines = [line for line in output_lines if line.lstrip().startswith("[")]
+        arrow_positions = [line.index("→") for line in finding_lines if "→" in line]
+        self.assertEqual(len(arrow_positions), 3)
+        self.assertEqual(len(set(arrow_positions)), 1, (
+            f"→ arrows not aligned — positions: {arrow_positions}"
+        ))
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_export_orchestrator_shape.py

@@ -0,0 +1,153 @@
+"""Export orchestrator — new [export.<backend>] config shape coverage.
+
+Glenn's amendment: the previous draft missed the fetch seam where
+``run_export`` reads ``config[resolved_backend]`` at lines 155 and 165. A
+stub-backend test that drives the actual ``run_export`` exposes this — it
+KeyErrors today if any site still reads the top-level key.
+"""
+
+from __future__ import annotations
+
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from loghunter import exporters
+from loghunter.exporters import run_export
+
+
+# ── backend selection reads config["export"][name], not top-level ────────────
+
+
+def test_backend_selection_reads_from_export_namespace(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path,
+) -> None:
+    """A config with [splunk] at the TOP level must NOT auto-select splunk —
+    the new clean-break shape requires [export.splunk]."""
+    config = {
+        "loghunter": {"export_dir": str(tmp_path)},
+        # WRONG shape — top-level [splunk]. Must NOT activate.
+        "splunk": {"host": "192.0.2.20", "port": 8089,
+                   "query": {"default": {"spl": "x"}}},
+    }
+    with pytest.raises(ValueError, match=r"No export backend configured"):
+        run_export(
+            config=config, backend=None, query_names=[],
+            since=datetime(2026, 6, 1), until=datetime(2026, 6, 2),
+            out=None, verbose=False,
+        )
+
+
+def test_backend_selection_from_export_namespace_succeeds(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path,
+) -> None:
+    config = {
+        "loghunter": {"export_dir": str(tmp_path)},
+        "export": {"splunk": {"host": "192.0.2.20", "port": 8089,
+                              "query": {"default": {"spl": "x"}}}},
+    }
+    # Stub fetch / write so no real Splunk call happens.
+    from loghunter.exporters import splunk as splunk_module
+    monkeypatch.setattr(
+        splunk_module, "fetch",
+        lambda *a, **kw: ([], {"units": 0, "unit_label": "chunks"}),
+    )
+    monkeypatch.setattr(splunk_module, "write", lambda rows, outpath, verbose: (0, {"bytes": 0, "paths": [outpath]}))
+    # Should auto-select splunk and not raise.
+    run_export(
+        config=config, backend=None, query_names=[],
+        since=datetime(2026, 6, 1), until=datetime(2026, 6, 2),
+        out=None, verbose=False,
+    )
+
+
+# ── run_export fetch-seam — stub backend, verify what gets passed in ────────
+
+
+class _StubBackend:
+    """Module-shaped stub: exposes the four duck-typed callables run_export
+    needs. captured = the kwargs each was called with."""
+
+    captured: dict[str, Any] = {}
+
+    @staticmethod
+    def is_configured(backend_cfg: dict) -> bool:
+        return bool(backend_cfg.get("host", "").strip())
+
+    @staticmethod
+    def summary_descriptor(backend_cfg: dict) -> str:
+        return backend_cfg.get("host", "")
+
+    @staticmethod
+    def fetch(query_config, backend_config, since, until, verbose, *, skip_confirm=False):
+        # Capture the backend_config the orchestrator hands us — this is the
+        # seam Glenn's amendment guards. Pre-fix, this would have arrived as
+        # config["splunk"] (top-level) and the new clean-break config has no
+        # such key → KeyError or empty dict.
+        _StubBackend.captured["backend_config"] = backend_config
+        _StubBackend.captured["query_config"] = query_config
+        return ([], {"units": 0, "unit_label": "chunks"})
+
+    @staticmethod
+    def write(rows, outpath, verbose):
+        _StubBackend.captured["outpath"] = outpath
+        return 0, {"bytes": 0, "paths": [outpath]}
+
+
+def test_run_export_fetch_receives_export_namespace_backend_config(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path,
+) -> None:
+    """Drive the actual run_export call. The fetch seam MUST receive the
+    [export.<stub>] stanza dict, not the empty top-level config['<stub>']."""
+    _StubBackend.captured = {}
+    # Register the stub under the existing splunk slot via monkeypatch on the
+    # loaded-module cache: the orchestrator does importlib on a name in
+    # _KNOWN_BACKENDS, then is_configured / fetch / write on that module.
+    monkeypatch.setattr(exporters, "_load_backend", lambda name: _StubBackend)
+    monkeypatch.setattr(exporters, "_KNOWN_BACKENDS", ("splunk",))
+
+    config = {
+        "loghunter": {"export_dir": str(tmp_path)},
+        "export": {"splunk": {
+            "host": "192.0.2.20",
+            "port": 8089,
+            "query": {"default": {"spl": "search *", "output_basename": "syslog"}},
+        }},
+        # Decoy: top-level key with junk. Pre-fix code would have read THIS.
+        "splunk": {"host": "BOGUS-do-not-use", "query": {}},
+    }
+    run_export(
+        config=config, backend="splunk", query_names=[],
+        since=datetime(2026, 6, 1), until=datetime(2026, 6, 2),
+        out=None, verbose=False,
+    )
+
+    backend_cfg = _StubBackend.captured["backend_config"]
+    assert backend_cfg.get("host") == "192.0.2.20"
+    assert backend_cfg.get("host") != "BOGUS-do-not-use"
+
+
+# ── Splunk no-query under [export.splunk] → actionable ValueError ────────────
+
+
+def test_splunk_no_query_under_export_namespace_raises_actionable(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path,
+) -> None:
+    """No shipped default query. [export.splunk] with host set but no query
+    stanza must raise a ValueError naming [export.splunk.query.<name>]."""
+    config = {
+        "loghunter": {"export_dir": str(tmp_path)},
+        "export": {"splunk": {"host": "192.0.2.20", "port": 8089}},
+        # NO query.* — bare loghunter export must surface an actionable error.
+    }
+    with pytest.raises(ValueError) as exc_info:
+        run_export(
+            config=config, backend=None, query_names=[],
+            since=datetime(2026, 6, 1), until=datetime(2026, 6, 2),
+            out=None, verbose=False,
+        )
+    msg = str(exc_info.value)
+    assert "[export.splunk.query." in msg