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

loghunter/detectors/dnsblock.py

@@ -0,0 +1,29 @@
+"""Dnsblock detector — behavioral anomalies in blocked DNS query patterns. (planned)
+
+Surfaces who is querying known-bad domains, how often, with what
+persistence, and across what spread of clients. Complements the dns
+detector: DNS clustering finds *unknown-bad* domains by behavioral
+fingerprint; dnsblock finds *known-bad-domain access patterns* by client
+behavior. Pi-hole/dnsmasq only — needs the `was_blocked` column that
+Zeek does not carry.
+"""
+
+from __future__ import annotations
+
+from loghunter.common.finding import DetectorContext, Finding
+
+DETECTOR_NAME = "dnsblock"
+STATUS = "planned"
+
+REQUIRED_LOGS = [
+    {"source": "pihole_dir", "pattern": "pihole*.log*"},
+]
+
+OPTIONAL_LOGS: list[dict] = []
+
+DEFAULT_CONFIG: dict = {}
+
+
+def run(context: DetectorContext) -> list[Finding]:
+    """Detect behavioral anomalies in blocked DNS query patterns."""
+    raise NotImplementedError("dnsblock detector is planned — not yet implemented")

loghunter/detectors/duration.py

@@ -0,0 +1,178 @@
+"""Duration detector — long-lived connection detection from Zeek conn.log.
+
+Flags connections that remain open for an unusually long time, which may indicate
+tunneling, C2 keep-alive sessions, or data exfiltration channels.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+import pandas as pd
+
+from loghunter.common.finding import DetectorContext, Finding, MethodTag, Severity
+
+DETECTOR_NAME = "duration"
+STATUS = "available"
+
+REQUIRED_LOGS = [
+    {"source": "zeek_dir", "pattern": "conn*.log*"},
+]
+
+OPTIONAL_LOGS: list[dict] = []
+
+DEFAULT_CONFIG = {
+    "min_duration_seconds": 1800,
+}
+
+DETECTOR_METHOD = MethodTag("heuristics", named=False)
+
+_DURATION_HIGH   = 14400  # 4 hours
+_DURATION_MEDIUM = 7200   # 2 hours
+
+
+def _duration_str(seconds: float) -> str:
+    """Return a compact human-readable string for a duration in seconds."""
+    s = int(seconds)
+    if s < 60:
+        return f"{s}s"
+    if s < 3600:
+        m, rem = divmod(s, 60)
+        return f"{m}m {rem}s"
+    if s < 86400:
+        h, rem = divmod(s, 3600)
+        return f"{h}h {rem // 60}m"
+    d, rem = divmod(s, 86400)
+    return f"{d}d {rem // 3600}h"
+
+
+def _to_severity(duration: float) -> Severity:
+    if duration >= _DURATION_HIGH:
+        return Severity.HIGH
+    if duration >= _DURATION_MEDIUM:
+        return Severity.MEDIUM
+    return Severity.LOW
+
+
+def run(context: DetectorContext) -> list[Finding]:
+    """Flag flows exceeding the minimum duration threshold, grouped by (src, dst, port, proto)."""
+    cfg: dict = {**DEFAULT_CONFIG, **context.config}
+    min_dur = cfg["min_duration_seconds"]
+
+    df = context.logs.get("conn*.log*")
+    if df is None or df.empty:
+        return []
+
+    if "duration" not in df.columns:
+        return []
+
+    df = df.copy()
+    df["duration"] = pd.to_numeric(df["duration"], errors="coerce")
+
+    df = df[df["duration"].notna() & (df["duration"] > 0)]
+    if df.empty:
+        return []
+
+    df = df[df["duration"] >= min_dur]
+    if df.empty:
+        return []
+
+    # Normalize grouping keys. Port may be NaN; fill with sentinel so groupby
+    # doesn't silently drop portless rows. dropna=False is a second safety net.
+    for col in ("src", "dst", "proto"):
+        if col not in df.columns:
+            df[col] = ""
+    if "port" in df.columns:
+        df["port"] = pd.to_numeric(df["port"], errors="coerce")
+    else:
+        df["port"] = float("nan")
+    df["_port_key"] = df["port"].fillna(-1).astype(int)
+
+    findings: list[Finding] = []
+    for (src, dst, port_key, proto), group in df.groupby(
+            ["src", "dst", "_port_key", "proto"], sort=False, dropna=False):
+
+        port: int | None = None if port_key == -1 else int(port_key)
+
+        max_row = group.loc[group["duration"].idxmax()]
+        max_dur = round(float(max_row["duration"]), 1)
+        max_dur_str = _duration_str(max_dur)
+
+        # total_bytes: None if column absent or all null
+        if "bytes" in group.columns:
+            bytes_series = group["bytes"].dropna()
+            total_bytes: int | None = int(bytes_series.sum()) if not bytes_series.empty else None
+        else:
+            total_bytes = None
+
+        # avg_bytes_per_second: derived from the max-duration row, not group total
+        avg_bps: float | None
+        if "bytes" in group.columns:
+            row_bytes = max_row["bytes"]
+            avg_bps = (
+                round(float(row_bytes) / max_dur, 1)
+                if pd.notna(row_bytes) and max_dur > 0
+                else None
+            )
+        else:
+            avg_bps = None
+
+        # conn_states: distinct non-null values, sorted; empty list if column absent
+        if "conn_state" in group.columns:
+            states: list[str] = sorted(group["conn_state"].dropna().unique().tolist())
+        else:
+            states = []
+
+        # first_seen / last_seen: UTC ISO strings from unix epoch seconds
+        if "ts" in group.columns:
+            ts_series = pd.to_numeric(group["ts"], errors="coerce").dropna()
+        else:
+            ts_series = pd.Series(dtype=float)
+        if not ts_series.empty:
+            first_seen: str | None = datetime.fromtimestamp(
+                float(ts_series.min()), tz=timezone.utc
+            ).isoformat()
+            last_seen: str | None = datetime.fromtimestamp(
+                float(ts_series.max()), tz=timezone.utc
+            ).isoformat()
+        else:
+            first_seen = last_seen = None
+
+        port_str = str(port) if port is not None else "?"
+        title = f"{src} → {dst}:{port_str}/{proto}"
+
+        severity = _to_severity(max_dur)
+
+        findings.append(Finding(
+            detector="duration",
+            severity=severity,
+            title=title,
+            description=(
+                "A long-lived connection may indicate tunneling, a C2 keep-alive session, "
+                "or an active data exfiltration channel."
+            ),
+            evidence={
+                "src":                  src,
+                "dst":                  dst,
+                "port":                 port,
+                "proto":                proto,
+                "max_duration_seconds": max_dur,
+                "max_duration_str":     max_dur_str,
+                "connection_count":     len(group),
+                "total_bytes":          total_bytes,
+                "avg_bytes_per_second": avg_bps,
+                "conn_states":          states,
+                "first_seen":           first_seen,
+                "last_seen":            last_seen,
+            },
+            next_steps=[
+                f"Review {max_dur_str} connection in conn.log: zeek-cut id.orig_h id.resp_h id.resp_p duration conn_state < conn.log | grep {src}",
+                "Check if this is expected infrastructure (VPN, backup, monitoring) — if so, add to allowlist",
+                f"For external destinations, run: whois {dst}",
+            ],
+            ts_generated=datetime.now(tz=timezone.utc),
+            data_window=context.data_window,
+        ))
+
+    findings.sort(key=lambda f: f.evidence["max_duration_seconds"], reverse=True)
+    return findings

loghunter/detectors/protocol.py

@@ -0,0 +1,26 @@
+"""Protocol detector — per-protocol autoencoder on connection metadata. (planned)
+
+Trains a per-protocol autoencoder on connection feature vectors derived from
+Zeek conn.log. High reconstruction error indicates anomalous session behavior
+for that protocol. Requires session-level feature data.
+"""
+
+from __future__ import annotations
+
+from loghunter.common.finding import DetectorContext, Finding
+
+DETECTOR_NAME = "protocol"
+STATUS = "planned"
+
+REQUIRED_LOGS = [
+    {"source": "zeek_dir", "pattern": "conn*.log*"},
+]
+
+OPTIONAL_LOGS: list[dict] = []
+
+DEFAULT_CONFIG: dict = {}
+
+
+def run(context: DetectorContext) -> list[Finding]:
+    """Detect anomalous sessions using per-protocol autoencoder reconstruction error."""
+    raise NotImplementedError("protocol detector is planned — not yet implemented")