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

tests/test_scan_detector.py

@@ -0,0 +1,455 @@
+"""Focused tests for the scan detector migration.
+
+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 sys
+import time
+import unittest
+from datetime import datetime, timezone
+
+import pandas as pd
+
+from loghunter.common.finding import DetectorContext, Finding, RunSummary, Severity
+from loghunter.detectors.scan import (
+    DETECTOR_NAME,
+    STATUS,
+    _classify_direction,
+    _make_finding,
+    _zone_of,
+    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)
+
+# Matches the shipped [loghunter].home_net default. Used here only so a
+# helper-built context behaves identically to a runner-built context for the
+# detector's RFC 5737 doc-space traffic fixtures — those addresses are outside
+# RFC1918 and read as external→external, matching pre-refactor behavior.
+_RFC1918_HOME_NET = ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"]
+
+
+def _ctx(
+    df: pd.DataFrame | None,
+    cfg: dict | None = None,
+    home_net: list[str] | None = None,
+) -> DetectorContext:
+    """Build a DetectorContext for scan tests.
+
+    home_net distinguishes None (apply RFC1918 default — same as runner supply
+    path with no operator override) from [] (intentionally empty, to exercise
+    the scan module's standalone-callable fallback constant). Tests that need
+    a specific zone layout pass home_net explicitly.
+    """
+    logs = {"conn*.log*": df} if df is not None else {}
+    return DetectorContext(
+        logs=logs,
+        config=cfg or {},
+        allowlist=None,
+        data_window=_WINDOW,
+        home_net=_RFC1918_HOME_NET if home_net is None else home_net,
+    )
+
+
+def _base_row(scan_type: str, src: str = "192.0.2.1") -> dict:
+    """Minimal classified result dict suitable for _make_finding."""
+    return {
+        "scan_type"        : scan_type,
+        "src"              : src,
+        "dst"              : "198.51.100.1" if scan_type == "vertical" else None,
+        "port"             : 22 if scan_type == "horizontal" else None,
+        "distinct_ports"   : 20,
+        "distinct_hosts"   : 20,
+        "total_conns"      : 100,
+        "scan_state_ratio" : 0.70,
+        "top_states"       : "S0, REJ",
+        "direction"        : "internal→external",
+        "pattern_tag"      : "confirmed_scan",
+        "pattern_notes"    : "Strong scanner signature.",
+        "window_start"     : "2026-05-30 00:00:00",
+        "window_secs"      : 3600,
+        "active_buckets"   : 5 if scan_type == "slow" else None,
+        "temporal_spread_score": 2.5 if scan_type == "slow" else None,
+        "max_ports_in_bucket"  : 4 if scan_type == "slow" else None,
+        "_severity"        : Severity.HIGH,
+    }
+
+
+def _conn_df(
+    src: str,
+    dst: str | None,
+    ports: list[int],
+    dsts: list[str] | None,
+    conn_state: str,
+    proto: str = "tcp",
+    base_ts: float = 1_748_563_200.0,
+    spacing: float = 60.0,
+) -> pd.DataFrame:
+    """Build a canonical-schema DataFrame for detector input."""
+    rows = []
+    if dsts is not None:
+        # horizontal — one port, many hosts
+        p = ports[0]
+        for i, d in enumerate(dsts):
+            rows.append({
+                "src"       : src,
+                "dst"       : d,
+                "port"      : p,
+                "proto"     : proto,
+                "ts"        : base_ts + i * spacing,
+                "conn_state": conn_state,
+            })
+    else:
+        # vertical — one host, many ports
+        for i, p in enumerate(ports):
+            rows.append({
+                "src"       : src,
+                "dst"       : dst,
+                "port"      : p,
+                "proto"     : proto,
+                "ts"        : base_ts + i * spacing,
+                "conn_state": conn_state,
+            })
+    return pd.DataFrame(rows)
+
+
+# ── Tests ─────────────────────────────────────────────────────────────────────
+
+class ScanDetectorTests(unittest.TestCase):
+
+    # ── Discovery ─────────────────────────────────────────────────────────────
+
+    def test_scan_is_available_in_discover_detectors(self) -> None:
+        detectors = discover_detectors()
+        self.assertIn("scan", detectors)
+        self.assertEqual(getattr(detectors["scan"], "STATUS", None), "available")
+
+    def test_detector_name_constant(self) -> None:
+        self.assertEqual(DETECTOR_NAME, "scan")
+        self.assertEqual(STATUS, "available")
+
+    # ── Empty / no input ──────────────────────────────────────────────────────
+
+    def test_run_returns_empty_on_no_logs(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", "conn_state"])
+        self.assertEqual(run(_ctx(empty)), [])
+
+    def test_icmp_rows_excluded(self) -> None:
+        df = _conn_df("192.0.2.1", "198.51.100.1",
+                      ports=list(range(1, 30)), dsts=None,
+                      conn_state="S0", proto="icmp")
+        self.assertEqual(run(_ctx(df)), [])
+
+    def test_malformed_but_loadable_rows_do_not_crash(self) -> None:
+        """Missing nullable-ish fields and string ports should be normalized safely."""
+        rows = []
+        for i, port in enumerate(range(1, 25)):
+            rows.append({
+                "src" : "192.0.2.1",
+                "dst" : None if i == 0 else "198.51.100.1",
+                "port": str(port),
+                "ts"  : 1_748_563_200.0 + i,
+            })
+        findings = run(_ctx(pd.DataFrame(rows), {"vertical_threshold": 15}))
+
+        self.assertIsInstance(findings, list)
+
+    def test_missing_port_column_returns_no_findings(self) -> None:
+        rows = []
+        for i in range(20):
+            rows.append({
+                "src"       : "192.0.2.1",
+                "dst"       : "198.51.100.1",
+                "proto"     : "tcp",
+                "ts"        : 1_748_563_200.0 + i,
+                "conn_state": "S0",
+            })
+        self.assertEqual(run(_ctx(pd.DataFrame(rows))), [])
+
+    def test_missing_ts_column_returns_no_findings(self) -> None:
+        rows = []
+        for port in range(1, 25):
+            rows.append({
+                "src"       : "192.0.2.1",
+                "dst"       : "198.51.100.1",
+                "port"      : port,
+                "proto"     : "tcp",
+                "conn_state": "S0",
+            })
+        self.assertEqual(run(_ctx(pd.DataFrame(rows))), [])
+
+    # ── Vertical scan ─────────────────────────────────────────────────────────
+
+    def test_vertical_scan_detected(self) -> None:
+        ports = list(range(1, 26))              # 25 distinct ports > threshold 15
+        df = _conn_df(
+            src="192.0.2.1",
+            dst="198.51.100.1",
+            ports=ports,
+            dsts=None,
+            conn_state="S0",
+            spacing=30.0,
+        )
+        findings = run(_ctx(df, {"vertical_threshold": 15}))
+        scan_findings = [f for f in findings if f.evidence["scan_type"] == "vertical"]
+        self.assertTrue(len(scan_findings) >= 1, "Expected at least one vertical finding")
+        self.assertIn(scan_findings[0].severity, (Severity.HIGH, Severity.MEDIUM))
+
+    def test_vertical_below_threshold_not_flagged(self) -> None:
+        ports = list(range(1, 10))              # 9 ports < threshold 15
+        df = _conn_df("192.0.2.1", "198.51.100.1",
+                      ports=ports, dsts=None, conn_state="S0")
+        findings = run(_ctx(df, {"vertical_threshold": 15}))
+        vertical = [f for f in findings if f.evidence["scan_type"] == "vertical"]
+        self.assertEqual(vertical, [])
+
+    # ── Horizontal scan ───────────────────────────────────────────────────────
+
+    def test_horizontal_scan_detected(self) -> None:
+        dsts = [f"198.51.100.{i}" for i in range(1, 31)]   # 30 distinct hosts
+        df = _conn_df(
+            src="192.0.2.1",
+            dst=None,
+            ports=[22],
+            dsts=dsts,
+            conn_state="REJ",
+            spacing=10.0,
+        )
+        findings = run(_ctx(df, {"horizontal_threshold": 15}))
+        horiz = [f for f in findings if f.evidence["scan_type"] == "horizontal"]
+        self.assertTrue(len(horiz) >= 1, "Expected at least one horizontal finding")
+        self.assertEqual(horiz[0].evidence["port"], 22)
+
+    # ── Block scan ────────────────────────────────────────────────────────────
+
+    def test_block_scan_detected(self) -> None:
+        # 25 ports × 25 hosts, all S0 → scan_state_ratio = 1.0
+        rows = []
+        base_ts = 1_748_563_200.0
+        for i, port in enumerate(range(1, 26)):
+            for j, host_n in enumerate(range(1, 26)):
+                rows.append({
+                    "src"       : "192.0.2.1",
+                    "dst"       : f"198.51.100.{host_n}",
+                    "port"      : port,
+                    "proto"     : "tcp",
+                    "ts"        : base_ts + (i * 25 + j),
+                    "conn_state": "S0",
+                })
+        df = pd.DataFrame(rows)
+        findings = run(_ctx(df, {
+            "block_port_threshold": 20,
+            "block_host_threshold": 20,
+            "block_state_min"     : 0.30,
+        }))
+        block = [f for f in findings if f.evidence["scan_type"] == "block"]
+        self.assertTrue(len(block) >= 1, "Expected at least one block finding")
+
+    # ── Slow scan ─────────────────────────────────────────────────────────────
+
+    def test_slow_scan_detected(self) -> None:
+        # 10 ports spread across 5 time buckets (one per bucket), all S0
+        bucket_secs = 3600.0
+        base_ts     = 1_748_563_200.0
+        rows = []
+        for bucket in range(5):
+            for port in range(bucket * 2 + 1, bucket * 2 + 3):   # 2 ports per bucket
+                rows.append({
+                    "src"       : "192.0.2.1",
+                    "dst"       : "198.51.100.1",
+                    "port"      : port,
+                    "proto"     : "tcp",
+                    "ts"        : base_ts + bucket * bucket_secs + 60,
+                    "conn_state": "S0",
+                })
+        df = pd.DataFrame(rows)
+        findings = run(_ctx(df, {
+            "slow_min_ports"   : 8,
+            "slow_min_buckets" : 4,
+            "slow_state_min"   : 0.30,
+            "window_secs"      : int(bucket_secs),
+            "vertical_threshold": 15,
+        }))
+        slow = [f for f in findings if f.evidence["scan_type"] == "slow"]
+        self.assertTrue(len(slow) >= 1, "Expected at least one slow scan finding")
+
+    # ── Finding construction ──────────────────────────────────────────────────
+
+    def test_make_finding_vertical_title(self) -> None:
+        # Title is flow/entity only — metrics belong in evidence, not title.
+        row = _base_row("vertical")
+        f   = _make_finding(row, _WINDOW)
+        self.assertIn("192.0.2.1", f.title)
+        self.assertIn("198.51.100.1", f.title)
+        self.assertNotIn("ports", f.title)
+        self.assertEqual(f.detector, "scan")
+        self.assertEqual(f.severity, Severity.HIGH)
+        # Metrics are in evidence
+        self.assertIn("distinct_ports", f.evidence)
+
+    def test_make_finding_horizontal_title(self) -> None:
+        row = _base_row("horizontal")
+        f   = _make_finding(row, _WINDOW)
+        self.assertIn("*:22", f.title)
+        self.assertNotIn("hosts", f.title)
+        self.assertIn("distinct_hosts", f.evidence)
+
+    def test_make_finding_block_title(self) -> None:
+        row = _base_row("block")
+        f   = _make_finding(row, _WINDOW)
+        self.assertIn("→ *", f.title)
+        self.assertNotIn("×", f.title)
+        self.assertIn("distinct_ports", f.evidence)
+        self.assertIn("distinct_hosts", f.evidence)
+
+    def test_make_finding_slow_title(self) -> None:
+        row = _base_row("slow")
+        f   = _make_finding(row, _WINDOW)
+        self.assertIn("slow scan", f.title)
+        self.assertNotIn("windows", f.title)
+        # Slow evidence includes temporal fields
+        self.assertIn("temporal_spread_score", f.evidence)
+        self.assertIn("active_buckets", f.evidence)
+
+    def test_make_finding_evidence_fields_present(self) -> None:
+        for scan_type in ("vertical", "horizontal", "block"):
+            row = _base_row(scan_type)
+            f   = _make_finding(row, _WINDOW)
+            for field in ("scan_type", "src", "scan_state_ratio", "pattern_tag"):
+                self.assertIn(field, f.evidence, f"Missing {field} in {scan_type} evidence")
+
+    # ── Text renderer ─────────────────────────────────────────────────────────
+
+    def test_text_renderer_scan_group(self) -> None:
+        """Render a mixed set of scan findings; verify key tokens and no exceptions."""
+        findings = [
+            _make_finding(_base_row("vertical"),   _WINDOW),
+            _make_finding(_base_row("horizontal"), _WINDOW),
+        ]
+        summary = RunSummary(
+            data_window=_WINDOW,
+            record_counts={"conn*.log*": 1000},
+            data_size_bytes=0,
+            detectors_run=["scan"],
+            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("ratio=", output)
+        self.assertIn("ports",  output)
+        self.assertIn("hosts",  output)
+        self.assertIn("vertical",    output)
+        self.assertIn("horizontal",  output)
+
+    def test_text_renderer_verbose_scan_group(self) -> None:
+        """Verbose mode emits description, evidence, and next steps."""
+        finding = _make_finding(_base_row("vertical"), _WINDOW)
+        summary = RunSummary(
+            data_window=_WINDOW,
+            record_counts={},
+            data_size_bytes=0,
+            detectors_run=["scan"],
+            detectors_skipped={},
+        )
+        stream  = io.StringIO()
+        handler = TextHandler(stream=stream, verbose_level=1)
+        handler.begin(summary)
+        handler.write([finding])
+        handler.end()
+
+        output = stream.getvalue()
+        self.assertIn("evidence:",    output)
+        self.assertIn("next steps:",  output)
+        self.assertIn("data window:", output)
+
+
+# ── Zone-label seam tests ─────────────────────────────────────────────────────
+#
+# Sample IPs use RFC 5737 documentation space throughout. Internal/external is
+# defined by a test-specific home_net (e.g. 192.0.2.0/24) so 192.0.2.x reads
+# as internal and 198.51.100.x / 203.0.113.x read as external — no RFC1918
+# addresses appear in any traffic fixture.
+
+
+def test_zone_of_returns_internal_for_home_net_ip() -> None:
+    assert _zone_of("192.0.2.10", ["192.0.2.0/24"]) == "internal"
+
+
+def test_zone_of_returns_external_for_outside_ip() -> None:
+    assert _zone_of("198.51.100.10", ["192.0.2.0/24"]) == "external"
+
+
+def test_zone_of_returns_external_for_unparseable_ip() -> None:
+    assert _zone_of("not-an-ip", ["192.0.2.0/24"]) == "external"
+
+
+def test_classify_direction_produces_four_byte_identical_strings() -> None:
+    """Two-zone case MUST yield exactly the legacy four direction strings.
+
+    Proves the mechanical f-string rendering produces byte-identical evidence
+    output for the pre-refactor case — so existing reports stay legible.
+    """
+    home_net = ["192.0.2.0/24"]
+    cases = [
+        # (src, dst, expected src_zone, expected dst_zone, expected rendered)
+        ("192.0.2.5",   "192.0.2.6",    "internal", "internal", "internal→internal"),
+        ("192.0.2.5",   "198.51.100.6", "internal", "external", "internal→external"),
+        ("198.51.100.5","192.0.2.6",    "external", "internal", "external→internal"),
+        ("198.51.100.5","203.0.113.6",  "external", "external", "external→external"),
+    ]
+    for src, dst, exp_src_zone, exp_dst_zone, exp_rendered in cases:
+        src_zone, dst_zone, rendered = _classify_direction(src, dst, home_net)
+        assert src_zone == exp_src_zone, (src, dst, src_zone)
+        assert dst_zone == exp_dst_zone, (src, dst, dst_zone)
+        assert rendered == exp_rendered, (src, dst, rendered)
+
+
+def test_run_falls_back_to_default_home_net_when_context_empty() -> None:
+    """Empty context.home_net activates scan's standalone-callable fallback.
+
+    Traffic is doc-space only (no RFC1918). With the RFC1918 fallback in
+    effect, every flow correctly classifies as ``external→external`` and
+    the populated ``direction`` column makes its way into evidence — proving
+    the fallback path activated and the column was populated, without
+    smuggling private addresses into the fixture. (A future test needing to
+    prove an internal-side classification through the empty-context path
+    should monkeypatch _DEFAULT_HOME_NET to a doc-space range instead.)
+    """
+    src = "198.51.100.10"
+    dsts = [f"203.0.113.{i}" for i in range(10, 35)]
+    df = _conn_df(src, None, [22], dsts, conn_state="S0")
+    ctx = DetectorContext(
+        logs={"conn*.log*": df},
+        config={},
+        allowlist=None,
+        data_window=_WINDOW,
+        home_net=[],
+    )
+    findings = run(ctx)
+    assert findings, "fallback should keep run() functional with empty context.home_net"
+    for f in findings:
+        assert f.evidence.get("direction") == "external→external", (
+            "RFC1918 fallback should classify doc-space src→doc-space dst as external→external"
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_search_paths.py

@@ -0,0 +1,50 @@
+"""Config search path — ``./loghunter.conf`` is GONE.
+
+Clean-break: no project-local config; user must use --config or one of the
+two remaining tiers (~/.loghunter/config.toml, /etc/loghunter/config.toml).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from loghunter.common import config as cfg
+
+
+def test_search_paths_does_not_include_project_local_loghunter_conf() -> None:
+    """SEARCH_PATHS must not carry ./loghunter.conf — the clean-break drop."""
+    paths_str = [str(p) for p in cfg.SEARCH_PATHS]
+    for p in paths_str:
+        assert not p.endswith("loghunter.conf"), (
+            f"./loghunter.conf is back in SEARCH_PATHS: {paths_str}"
+        )
+
+
+def test_search_paths_carries_user_and_system_only() -> None:
+    paths_str = [str(p) for p in cfg.SEARCH_PATHS]
+    # User dir (expanded) and /etc both present.
+    assert any(p.endswith(".loghunter/config.toml") for p in paths_str)
+    assert "/etc/loghunter/config.toml" in paths_str
+    # Exactly two tiers — keep the precedence list tight.
+    assert len(paths_str) == 2
+
+
+def test_stray_loghunter_conf_in_cwd_is_not_picked_up(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path,
+) -> None:
+    """Create a ./loghunter.conf in CWD with a sentinel value. cfg.load() must
+    NOT pick it up — only --config explicit + the two remaining tiers."""
+    monkeypatch.chdir(tmp_path)
+    stray = tmp_path / "loghunter.conf"
+    stray.write_text('[loghunter]\nzeek_dir = "/should-never-load"\n', encoding="utf-8")
+    # Point the two remaining search paths at nonexistent locations so cfg.load
+    # falls back to _DEFAULTS rather than picking up the stray.
+    monkeypatch.setattr(
+        cfg, "SEARCH_PATHS",
+        [tmp_path / "no-user-config", tmp_path / "no-etc-config"],
+    )
+    config = cfg.load(config_file=None)
+    # Defaults shipped, not the sentinel.
+    assert config["loghunter"].get("zeek_dir") != "/should-never-load"