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

tests/test_syslog_detector.py

@@ -0,0 +1,458 @@
+"""Tests for the syslog anomaly detector.
+
+All IP addresses and hostnames use RFC 5737 documentation space:
+  192.0.2.x, 198.51.100.x, 203.0.113.x
+No real network data appears anywhere in this file.
+
+Strategy: run() tests monkeypatch _run_drain3 to inject pre-labelled template
+columns, so test outcomes are independent of drain3 clustering behaviour.
+The drain3 function itself has its own smoke test.
+"""
+
+from __future__ import annotations
+
+import unittest
+from datetime import datetime, timezone
+from unittest.mock import patch
+
+import pandas as pd
+
+from loghunter.common.finding import DetectorContext, Finding, Severity
+from loghunter.detectors.syslog import (
+    DETECTOR_NAME,
+    STATUS,
+    _run_drain3,
+    run,
+)
+from loghunter.outputs.text import Section as _Section
+
+
+def _flat_section(findings: list[Finding]) -> list[_Section]:
+    """Wrap findings into the single-section shape per the W2 renderer contract."""
+    return [_Section(None, list(findings), len(findings))]
+
+_NOW    = datetime(2026, 5, 30, tzinfo=timezone.utc)
+_WINDOW = (_NOW, _NOW)
+
+# Fixed unix epoch used across fixtures (2026-05-30 00:00:00 UTC)
+_BASE_TS = 1_748_563_200.0
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def _make_df(rows: list[dict]) -> pd.DataFrame:
+    return pd.DataFrame(rows, columns=["ts", "host", "raw", "message"])
+
+
+def _ctx(df: pd.DataFrame, cfg: dict | None = None) -> DetectorContext:
+    return DetectorContext(
+        logs={"*.log*": df},
+        config=cfg or {},
+        allowlist=None,
+        data_window=_WINDOW,
+    )
+
+
+def _common_row(i: int, ts_offset: float = 0.0) -> dict:
+    """A row whose message belongs to the high-frequency common template."""
+    return {
+        "ts":      _BASE_TS + ts_offset + i * 60.0,
+        "host":    "192.0.2.1",
+        "raw":     f"<30>May 30 12:{i:02d}:00 192.0.2.1 sshd[*]: Accepted publickey for admin",
+        "message": "sshd[*]: Accepted publickey for admin",
+    }
+
+
+def _patched_drain3(template_id_col: list[int], template_str_col: list[str]):
+    """Return a mock for _run_drain3 that injects pre-set template columns."""
+    def _mock(df: pd.DataFrame, *args, **kwargs) -> pd.DataFrame:
+        df = df.copy()
+        df["template_id"]  = template_id_col
+        df["template_str"] = template_str_col
+        return df
+    return _mock
+
+
+# ── Tests ─────────────────────────────────────────────────────────────────────
+
+class SyslogDetectorTests(unittest.TestCase):
+
+    # ── Constants ─────────────────────────────────────────────────────────────
+
+    def test_status_and_name_constants(self) -> None:
+        self.assertEqual(STATUS, "available")
+        self.assertEqual(DETECTOR_NAME, "syslog")
+
+    # ── Empty input ───────────────────────────────────────────────────────────
+
+    def test_run_returns_empty_on_empty_dataframe(self) -> None:
+        empty = _make_df([])
+        self.assertEqual(run(_ctx(empty)), [])
+
+    def test_run_returns_empty_when_logs_key_absent(self) -> None:
+        ctx = DetectorContext(
+            logs={},
+            config={},
+            allowlist=None,
+            data_window=_WINDOW,
+        )
+        self.assertEqual(run(ctx), [])
+
+    # ── Anomalous findings ────────────────────────────────────────────────────
+
+    def test_run_returns_medium_findings_for_anomalous_rows(self) -> None:
+        """One rare template (count=1) among 50 common rows → one MEDIUM finding."""
+        rows = [_common_row(i) for i in range(50)]
+        rows.append({
+            "ts":      _BASE_TS + 3600.0,
+            "host":    "192.0.2.1",
+            "raw":     "<30>May 30 13:00:00 192.0.2.1 kernel: RARE_SENTINEL xyzzy_anomaly",
+            "message": "kernel: RARE_SENTINEL xyzzy_anomaly",
+        })
+        df = _make_df(rows)
+
+        # template_id=1 for 50 common rows, template_id=2 for the rare row
+        ids  = [1] * 50 + [2]
+        strs = ["sshd[*]: Accepted publickey for admin"] * 50 + ["kernel: RARE_SENTINEL <*>"]
+
+        with patch("loghunter.detectors.syslog._run_drain3", _patched_drain3(ids, strs)):
+            findings = run(_ctx(df, {"max_count": 1, "rarity_pct": 10}))
+
+        self.assertEqual(len(findings), 1)
+        self.assertEqual(findings[0].detector, "syslog")
+        self.assertEqual(findings[0].severity, Severity.MEDIUM)
+
+    def test_medium_finding_evidence_fields(self) -> None:
+        """Evidence contains host, template_id (int), template_str, count, threshold."""
+        rows = [_common_row(i) for i in range(50)]
+        rows.append({
+            "ts":      _BASE_TS + 3600.0,
+            "host":    "192.0.2.2",
+            "raw":     "<30>May 30 13:00:00 192.0.2.2 cron[*]: Evidence fields test",
+            "message": "cron[*]: Evidence fields test",
+        })
+        df = _make_df(rows)
+        ids  = [1] * 50 + [99]
+        strs = ["sshd[*]: Accepted publickey for admin"] * 50 + ["cron[*]: Evidence <*> test"]
+
+        with patch("loghunter.detectors.syslog._run_drain3", _patched_drain3(ids, strs)):
+            findings = run(_ctx(df, {"max_count": 1, "rarity_pct": 10}))
+
+        self.assertEqual(len(findings), 1)
+        ev = findings[0].evidence
+        self.assertEqual(ev["host"], "192.0.2.2")
+        self.assertIsInstance(ev["template_id"], int)
+        self.assertIsInstance(ev["count"], int)
+        self.assertIsInstance(ev["threshold"], int)
+        self.assertIn("template_str", ev)
+
+    # ── Reboot suppression ────────────────────────────────────────────────────
+
+    def test_synthetic_reboot_finding_and_suppression(self) -> None:
+        """Post-reboot anomalous events are suppressed; a synthetic INFO finding appears."""
+        rows = [_common_row(i) for i in range(50)]
+
+        # Reboot signal row — matches is_reboot_signal() via "kernel: Linux version "
+        rows.append({
+            "ts":      _BASE_TS,
+            "host":    "192.0.2.1",
+            "raw":     "<30>May 30 00:00:00 192.0.2.1 kernel: Linux version 5.15.0",
+            "message": "kernel: Linux version 5.15.0",
+        })
+
+        # Anomalous post-reboot event, within 300s suppress window
+        rows.append({
+            "ts":      _BASE_TS + 100.0,
+            "host":    "192.0.2.1",
+            "raw":     "<30>May 30 00:01:40 192.0.2.1 kernel: POST_REBOOT_ANOMALY_SENTINEL",
+            "message": "kernel: POST_REBOOT_ANOMALY_SENTINEL",
+        })
+
+        df = _make_df(rows)
+
+        # 50 common (id=1), reboot signal (id=2, count=1 → anomalous), post-reboot (id=3, count=1 → anomalous)
+        ids  = [1] * 50 + [2, 3]
+        strs = ["sshd[*]: Accepted publickey for admin"] * 50 + [
+            "kernel: Linux version <*>",
+            "kernel: POST_REBOOT_ANOMALY_SENTINEL",
+        ]
+
+        with patch("loghunter.detectors.syslog._run_drain3", _patched_drain3(ids, strs)):
+            findings = run(_ctx(df, {"max_count": 1, "rarity_pct": 10}))
+
+        info_findings   = [f for f in findings if f.severity == Severity.INFO]
+        medium_findings = [f for f in findings if f.severity == Severity.MEDIUM]
+
+        # Synthetic reboot INFO finding present
+        self.assertTrue(len(info_findings) >= 1, "Expected at least one INFO (reboot) finding")
+        reboot_titles = [f.title.lower() for f in info_findings]
+        self.assertTrue(
+            any("reboot" in t for t in reboot_titles),
+            f"Expected 'reboot' in at least one INFO finding title, got: {reboot_titles}",
+        )
+
+        # Post-reboot anomalous event (template_id=3) is suppressed — must not appear as MEDIUM
+        medium_template_ids = [f.evidence.get("template_id") for f in medium_findings]
+        self.assertNotIn(
+            3, medium_template_ids,
+            "Post-reboot anomalous event (template_id=3) should be suppressed, not a MEDIUM finding",
+        )
+
+    # ── Text renderer ─────────────────────────────────────────────────────────
+
+    def test_text_renderer_syslog_group(self) -> None:
+        """Default syslog output keeps template/count details behind verbose."""
+        from loghunter.outputs.text import TextHandler
+
+        medium_f = Finding(
+            detector="syslog",
+            severity=Severity.MEDIUM,
+            title="May 30 14:23:01 router sshd[100]: Failed password for root",
+            description="Rare template",
+            evidence={
+                "host": "router", "template_id": 47,
+                "template_str": "sshd[*]: Failed password for <*>",
+                "count": 1, "threshold": 3,
+            },
+            next_steps=[],
+            ts_generated=_NOW,
+            data_window=_WINDOW,
+        )
+        info_f = Finding(
+            detector="syslog",
+            severity=Severity.INFO,
+            title="*** host1 rebooted ***",
+            description="Reboot detected",
+            evidence={
+                "host": "host1",
+                "reboot_ts": "2026-05-30T02:14:00+00:00",
+                "suppressed_window_seconds": 300,
+            },
+            next_steps=[],
+            ts_generated=_NOW,
+            data_window=_WINDOW,
+        )
+
+        handler = TextHandler(verbose_level=0)
+        rendered = handler._render_syslog_group(_flat_section([medium_f, info_f]))
+
+        medium_out = rendered[0]
+        self.assertNotIn("\n", medium_out)
+        self.assertIn("May 30 14:23:01 router sshd[100]", medium_out)
+        self.assertNotIn("count=", medium_out)
+        self.assertNotIn("thresh=", medium_out)
+        self.assertNotIn("template_id", medium_out)
+        self.assertNotIn("template:", medium_out)
+
+        # INFO: single line with "reboot @"
+        info_out = rendered[1]
+        self.assertNotIn("\n", info_out)
+        self.assertIn("reboot @", info_out)
+
+        self.assertTrue(medium_out.startswith("[M]  May 30"))
+        self.assertTrue(info_out.startswith("[I]  host1   "))
+
+    def test_text_renderer_syslog_verbose_shows_template_details(self) -> None:
+        """Verbose syslog output includes rarity and drain3 template internals."""
+        from loghunter.outputs.text import TextHandler
+
+        medium_f = Finding(
+            detector="syslog",
+            severity=Severity.MEDIUM,
+            title="May 30 14:23:01 router sshd[100]: Failed password for root",
+            description="Rare template",
+            evidence={
+                "host": "router", "template_id": 47,
+                "template_str": "sshd[*]: Failed password for <*>",
+                "count": 1, "threshold": 3,
+            },
+            next_steps=["Review surrounding log context for this host"],
+            ts_generated=_NOW,
+            data_window=_WINDOW,
+        )
+
+        rendered = "\n".join(
+            TextHandler(verbose_level=1)._render_syslog_group(_flat_section([medium_f]))
+        )
+
+        self.assertIn("May 30 14:23:01 router sshd[100]", rendered)
+        # W3 curated subset for syslog (template): template_str, host, count, threshold.
+        # template_id is internal — only surfaced under -vv (debug tail).
+        self.assertIn("template_str: sshd[*]: Failed password for <*>", rendered)
+        self.assertIn("count: 1", rendered)
+        self.assertIn("threshold: 3", rendered)
+        self.assertIn("Rare template", rendered)
+        self.assertIn("next steps:", rendered)
+
+    # ── drain3 smoke test ─────────────────────────────────────────────────────
+
+    def test_run_drain3_adds_columns(self) -> None:
+        """_run_drain3 must add non-null template_id and template_str columns."""
+        rows = [
+            {"ts": _BASE_TS + i, "host": "192.0.2.1",
+             "raw": f"line {i}", "message": msg}
+            for i, msg in enumerate([
+                "sshd[*]: session opened for user admin",
+                "sshd[*]: session opened for user root",
+                "sshd[*]: session closed for user admin",
+                "kernel: device eth0 entered promiscuous mode",
+                "kernel: device eth1 entered promiscuous mode",
+            ])
+        ]
+        df = _make_df(rows)
+        result = _run_drain3(df, sim_thresh=0.5, depth=4, parametrize_numeric=True)
+
+        self.assertIn("template_id", result.columns)
+        self.assertIn("template_str", result.columns)
+        self.assertFalse(result["template_id"].isna().any(), "template_id should have no nulls")
+        self.assertFalse(result["template_str"].isna().any(), "template_str should have no nulls")
+        self.assertEqual(len(result), len(df))
+
+
+# ── Fidelity-aware v1: dns-shape REQUIRES_ONE_OF_OPTIONAL contract ──────────
+
+
+def _zeek_syslog_row(i: int, ts_offset: float = 0.0) -> dict:
+    """A Zeek-frame syslog row with facility/severity carried.
+
+    Detector is source-blind — facility/severity must ride along without ever
+    being read. The frame carries the minimal-5 plus the extended pair.
+    """
+    return {
+        "ts":       _BASE_TS + ts_offset + i * 60.0,
+        "host":     "192.0.2.1",
+        "program":  "sshd",
+        "raw":      f"Jun 11 12:{i:02d}:00 host1 sshd[1234]: Accepted publickey for user",
+        "message":  "sshd[*]: Accepted publickey for user",
+        "facility": "DAEMON",
+        "severity": "INFO",
+    }
+
+
+def _ctx_zeek_only(df: pd.DataFrame, cfg: dict | None = None) -> DetectorContext:
+    """Context with frame keyed at the Zeek-syslog pattern key only."""
+    return DetectorContext(
+        logs={"syslog*.log*": df},
+        config=cfg or {},
+        allowlist=None,
+        data_window=_WINDOW,
+    )
+
+
+def _ctx_both(
+    flat_df: pd.DataFrame, zeek_df: pd.DataFrame, cfg: dict | None = None,
+) -> DetectorContext:
+    """Context with BOTH source keys populated (concat path)."""
+    return DetectorContext(
+        logs={"*.log*": flat_df, "syslog*.log*": zeek_df},
+        config=cfg or {},
+        allowlist=None,
+        data_window=_WINDOW,
+    )
+
+
+def test_detector_module_exposes_dns_shape_optional_contract() -> None:
+    """REQUIRED_LOGS empty; OPTIONAL_LOGS lists both feeds; ONE-OF gate on."""
+    import loghunter.detectors.syslog as mod
+    assert mod.REQUIRED_LOGS == []
+    assert {(o["source"], o["pattern"]) for o in mod.OPTIONAL_LOGS} == {
+        ("syslog_dir", "*.log*"),
+        ("zeek_dir",   "syslog*.log*"),
+    }
+    assert mod.REQUIRES_ONE_OF_OPTIONAL is True
+    assert mod.REQUIRES_ONE_OF_OPTIONAL_REASON == (
+        "syslog — no syslog source found "
+        "(need syslog_dir files or zeek_dir syslog.log)"
+    )
+
+
+def test_run_returns_empty_when_no_source_frames_present() -> None:
+    """Both pattern keys absent → empty findings. REQUIRES_ONE_OF_OPTIONAL
+    is enforced upstream by the runner; the detector itself degrades cleanly
+    when called with no frames."""
+    ctx = DetectorContext(
+        logs={}, config={}, allowlist=None,
+        data_window=_WINDOW,
+    )
+    assert run(ctx) == []
+
+
+def test_run_zeek_only_context_produces_findings_and_is_source_blind() -> None:
+    """Zeek frame (with facility/severity) drives detection; detector never
+    touches the extended columns. Source-blindness rail: the row tuples used
+    in the detector body have NO facility/severity attribute access."""
+    rows = [_zeek_syslog_row(i) for i in range(20)]
+    rows.append({
+        "ts":       _BASE_TS + 30 * 60.0,
+        "host":     "192.0.2.1",
+        "program":  "kernel",
+        "raw":      "Jun 11 12:30:00 host1 kernel: rare placeholder event",
+        "message":  "kernel: rare placeholder event",
+        "facility": "KERN",
+        "severity": "ERR",
+    })
+    df = pd.DataFrame(rows)
+    # Inject a stable template-id split: 20 commons + 1 rare.
+    template_ids  = [1] * 20 + [2]
+    template_strs = ["common"] * 20 + ["rare"]
+
+    with patch(
+        "loghunter.detectors.syslog._run_drain3",
+        _patched_drain3(template_ids, template_strs),
+    ):
+        findings = run(_ctx_zeek_only(df))
+
+    # One rare → at least one finding (drain3 patched to a known split).
+    assert any(f.severity == Severity.MEDIUM for f in findings)
+
+
+def test_run_concats_both_frames_in_order(monkeypatch) -> None:
+    """When both pattern keys are populated, run() concats flat + Zeek before
+    drain3 — the precedent is detectors/dns.py:_run_zeek_path-and-pihole-enrichment.
+    Asserts the concatenated frame's row count matches sum-of-inputs, proving
+    no de-dup / drop on union."""
+    flat_rows = [_common_row(i) for i in range(5)]
+    zeek_rows = [_zeek_syslog_row(i, ts_offset=10_000.0) for i in range(3)]
+    flat_df = pd.DataFrame(flat_rows)
+    zeek_df = pd.DataFrame(zeek_rows)
+
+    seen_lengths: list[int] = []
+
+    def _capture_drain3(df, *args, **kwargs):
+        seen_lengths.append(len(df))
+        df = df.copy()
+        df["template_id"]  = [1] * len(df)
+        df["template_str"] = ["common"] * len(df)
+        return df
+
+    monkeypatch.setattr(
+        "loghunter.detectors.syslog._run_drain3", _capture_drain3
+    )
+    run(_ctx_both(flat_df, zeek_df))
+    assert seen_lengths == [len(flat_rows) + len(zeek_rows)]
+
+
+def test_run_source_blind_no_facility_severity_required(monkeypatch) -> None:
+    """A frame missing facility/severity entirely still runs (flat-shape on
+    the Zeek key). Verifies the detector body references no extended column."""
+    rows = [_common_row(i) for i in range(20)]
+    rows.append({
+        "ts":      _BASE_TS + 30 * 60.0,
+        "host":    "192.0.2.1",
+        "program": "kernel",
+        "raw":     "Jun 11 12:30:00 host1 kernel: rare placeholder",
+        "message": "kernel: rare placeholder",
+    })
+    df = pd.DataFrame(rows)
+    template_ids  = [1] * 20 + [2]
+    template_strs = ["common"] * 20 + ["rare"]
+    monkeypatch.setattr(
+        "loghunter.detectors.syslog._run_drain3",
+        _patched_drain3(template_ids, template_strs),
+    )
+    findings = run(_ctx_zeek_only(df))
+    assert findings, "detector must run on a minimal-5 frame keyed at the Zeek pattern"
+
+
+if __name__ == "__main__":
+    unittest.main()