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

tests/test_dns_detector.py

@@ -0,0 +1,1010 @@
+"""Direct tests for the DNS detector — minimal-schema readiness and feature matrix.
+
+All IP addresses use RFC 5737 documentation space: 192.0.2.x, 198.51.100.x.
+All domains are placeholders — no real hostnames or infrastructure.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from types import SimpleNamespace
+
+import numpy as np
+import pandas as pd
+import pytest
+
+from loghunter.common import clustering
+from loghunter.common.finding import DetectorContext, Finding, Severity
+from loghunter.outputs.text import TextHandler, _partition_dns as _dns_sections
+from loghunter.detectors.dns import (
+    DEFAULT_CONFIG,
+    _build_features,
+    _build_pihole_aggregate,
+    _build_pihole_features,
+    _enrich_zeek_with_pihole,
+    _shared_back_half,
+    entropy as dns_entropy,
+    run,
+)
+
+
+@pytest.fixture(autouse=True)
+def _in_process_clustering(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Force the in-process escape hatch for every detector-logic test.
+
+    Detector-logic tests in this file do NOT exercise the process-isolation
+    machinery — that has its own dedicated suite in
+    tests/test_clustering_interruptible.py. Keeping these tests in-process
+    avoids spawn overhead per test and keeps the mock target visible to
+    the parent process.
+
+    The mock target IS ``loghunter.common.clustering.HDBSCAN`` — NOT
+    ``loghunter.detectors.dns.HDBSCAN``: the dns detector no longer
+    imports HDBSCAN, and even if it did, ``fit_predict_interruptible``'s
+    in-process path constructs ``clustering.HDBSCAN`` directly. Patching
+    the dns-module symbol would intercept nothing.
+    """
+    monkeypatch.setattr(
+        clustering, "_CLUSTERING_ISOLATE_ENABLED", False,
+    )
+
+_NOW = datetime(2026, 5, 30, tzinfo=timezone.utc)
+_WINDOW = (_NOW, _NOW)
+
+
+def _ctx(df: pd.DataFrame, cfg: dict | None = None) -> DetectorContext:
+    return DetectorContext(
+        logs={"dns*.log*": df},
+        config=cfg or {},
+        allowlist=None,
+        data_window=_WINDOW,
+    )
+
+
+def _fake_extract(query: str) -> SimpleNamespace:
+    """Stable tldextract stub — avoids cache writes; returns plausible attributes."""
+    return SimpleNamespace(
+        domain="example",
+        suffix="com",
+        subdomain="",
+        top_domain_under_public_suffix="example.com",
+    )
+
+
+# ── Test 1 — minimal-schema run() doesn't raise ───────────────────────────────
+
+def test_run_minimal_schema_does_not_raise(monkeypatch) -> None:
+    """dns.run() with only ts/src/query returns a list without raising.
+
+    tldextract is patched to avoid cache writes (PermissionError in sandboxes).
+    HDBSCAN config is set small so the test exercises the schema path, not calibration.
+    """
+    import loghunter.detectors.dns as dns_mod
+    monkeypatch.setattr(dns_mod.tldextract, "extract", _fake_extract)
+
+    df = pd.DataFrame([
+        {"ts": 1.0, "src": "192.0.2.1", "query": "api.test.example.com"},
+        {"ts": 2.0, "src": "192.0.2.2", "query": "beacon.test.example.net"},
+        {"ts": 3.0, "src": "192.0.2.1", "query": "cdn.example.com"},
+        {"ts": 4.0, "src": "192.0.2.3", "query": "dns.test.example.net"},
+    ])
+    ctx = _ctx(df, cfg={"min_cluster_size": 2, "min_samples": 1})
+    result = run(ctx)
+    assert isinstance(result, list)
+
+
+# ── Test 2 — _build_features minimal schema → query-derived only ─────────────
+
+def test_build_features_minimal_schema_omits_extended_columns() -> None:
+    """With only ts/src/query, extended features must be absent (drop-from-matrix, not zero-fill).
+
+    Queries include both .com and .net TLDs so pd.get_dummies(drop_first=True)
+    still produces at least one TLD_ column.
+    """
+    df = pd.DataFrame([
+        {"ts": 1.0, "src": "192.0.2.1", "query": "api.test.example.com"},
+        {"ts": 2.0, "src": "192.0.2.2", "query": "beacon.test.example.net"},
+        {"ts": 3.0, "src": "192.0.2.1", "query": "cdn.example.com"},
+        {"ts": 4.0, "src": "192.0.2.3", "query": "resolve.test.example.net"},
+    ])
+    feat = _build_features(df)
+
+    for col in ("qlen", "qparts", "sufflen", "domlen"):
+        assert col in feat.columns, f"expected query-derived column {col!r} in feature matrix"
+
+    tld_cols = [c for c in feat.columns if c.startswith("TLD_")]
+    assert len(tld_cols) >= 1, "expected at least one TLD_ one-hot column"
+
+    for col in ("rtt", "ttl", "rcode", "answer", "tc"):
+        assert col not in feat.columns, (
+            f"{col!r} must be absent from feature matrix when not present in input "
+            "(drop-from-matrix, not zero-fill)"
+        )
+
+
+# ── Test 3 — _build_features extended schema → extended features included ─────
+
+def test_build_features_extended_schema_includes_extended_columns() -> None:
+    """When canonical extended columns are present they appear in the feature matrix."""
+    df = pd.DataFrame([
+        {
+            "ts": 1.0, "src": "192.0.2.1", "query": "api.example.com",
+            "rtt": 0.05, "ttl": 300.0, "rcode": 0,
+            "answer": ["198.51.100.1"], "tc": 0,
+        },
+        {
+            "ts": 2.0, "src": "192.0.2.2", "query": "cdn.example.net",
+            "rtt": 0.03, "ttl": 60.0, "rcode": 0,
+            "answer": ["198.51.100.5", "198.51.100.6"], "tc": 0,
+        },
+    ])
+    feat = _build_features(df)
+
+    for col in ("rtt", "ttl", "rcode", "answer", "tc"):
+        assert col in feat.columns, f"expected extended column {col!r} in feature matrix"
+
+
+# ── Test 4 — Zeek path golden regression ─────────────────────────────────────
+
+# Fixture: 6 rows — 1 filtered (single-label), 2 cluster-0, 3 noise.
+# Noise group: a3f7bc19.malware.example + m8x2q9n.malware.example → malware.example group finding.
+# Noise singleton: k8x2m5q7n1p.suspect.example → singleton finding.
+#
+# After the Commit-2 refactor, the ONLY permitted change is the additive
+# evidence key source="zeek". All other keys and values must match exactly.
+# Assert (a) exact final order, (b) every pre-refactor evidence key unchanged,
+# (c) the only new key in post-refactor output is source=="zeek".
+
+_REGRESSION_DF = pd.DataFrame([
+    {"ts": 1.0, "src": "192.0.2.1", "query": "localhost"},               # single-label → filtered by has_dot
+    {"ts": 2.0, "src": "192.0.2.2", "query": "safe.example.com"},        # cluster 0
+    {"ts": 3.0, "src": "192.0.2.3", "query": "normal.example.org"},      # cluster 0
+    {"ts": 4.0, "src": "192.0.2.1", "query": "a3f7bc19.malware.example"},    # noise → group
+    {"ts": 5.0, "src": "192.0.2.2", "query": "m8x2q9n.malware.example"},     # noise → group
+    {"ts": 6.0, "src": "192.0.2.1", "query": "k8x2m5q7n1p.suspect.example"}, # noise → singleton
+])
+
+# Per-query tldextract results — deterministic, avoids cache writes.
+# localhost included so the degenerate filter path is exercised via has_dot.
+_REGRESSION_EXT = {
+    "localhost":               SimpleNamespace(domain="localhost", suffix="",    subdomain="",            top_domain_under_public_suffix=""),
+    "safe.example.com":        SimpleNamespace(domain="example",  suffix="com",  subdomain="safe",         top_domain_under_public_suffix="example.com"),
+    "normal.example.org":      SimpleNamespace(domain="example",  suffix="org",  subdomain="normal",       top_domain_under_public_suffix="example.org"),
+    "a3f7bc19.malware.example":    SimpleNamespace(domain="malware",  suffix="example",  subdomain="a3f7bc19",     top_domain_under_public_suffix="malware.example"),
+    "m8x2q9n.malware.example":     SimpleNamespace(domain="malware",  suffix="example",  subdomain="m8x2q9n",      top_domain_under_public_suffix="malware.example"),
+    "k8x2m5q7n1p.suspect.example": SimpleNamespace(domain="suspect",  suffix="example",  subdomain="k8x2m5q7n1p",  top_domain_under_public_suffix="suspect.example"),
+}
+
+
+def _regression_fake_extract(q: str) -> SimpleNamespace:
+    return _REGRESSION_EXT.get(
+        q,
+        SimpleNamespace(domain="", suffix="", subdomain="", top_domain_under_public_suffix=""),
+    )
+
+
+# After degenerate filter, dns_df has 5 rows in this order (localhost dropped):
+#   0: safe.example.com, 1: normal.example.org,
+#   2: a3f7bc19.malware.example, 3: m8x2q9n.malware.example, 4: k8x2m5q7n1p.suspect.example
+# FakeHDBSCAN puts rows 0–1 in cluster 0, rows 2–4 as noise.
+class _FakeHDBSCAN:
+    def __init__(self, **kwargs): pass
+    def fit_predict(self, X: np.ndarray) -> np.ndarray:
+        return np.array([0, 0, -1, -1, -1])
+
+
+def test_zeek_path_regression(monkeypatch) -> None:
+    """Golden: Zeek path produces a group + singleton finding in exact order.
+
+    Commit 2 may ONLY add source='zeek' to each finding's evidence.
+    Every pre-existing key and value must be identical after the refactor.
+    """
+    import loghunter.detectors.dns as dns_mod
+
+    monkeypatch.setattr(dns_mod.tldextract, "extract", _regression_fake_extract)
+    monkeypatch.setattr(clustering, "HDBSCAN", _FakeHDBSCAN)
+
+    # Expected entropy values derived from the actual entropy() function —
+    # no hardcoded floats; if entropy() changes the test will catch it.
+    ent_a3f7bc19 = dns_entropy("a3f7bc19")      # subdomain of a3f7bc19.malware.example
+    ent_m8x2q9n  = dns_entropy("m8x2q9n")       # subdomain of m8x2q9n.malware.example
+    ent_suspect  = dns_entropy("k8x2m5q7n1p")   # subdomain of k8x2m5q7n1p.suspect.example
+
+    ctx = DetectorContext(
+        logs={"dns*.log*": _REGRESSION_DF.copy()},
+        config={"min_cluster_size": 5, "min_samples": 1, "threshold": 1.5, "thresh_high_entropy": 1.8},
+        allowlist=None,
+        data_window=(_NOW, _NOW),
+    )
+    findings = run(ctx)
+
+    # ── Exact count ───────────────────────────────────────────────────────────
+    assert len(findings) == 2, f"expected 2 findings, got {len(findings)}: {[f.title for f in findings]}"
+
+    # ── Exact order: group first (sorted by max_entropy desc), then singletons ─
+    golden_titles = [
+        "malware.example (2 subdomains, entropy ≥ 1.8)",
+        "k8x2m5q7n1p.suspect.example",
+    ]
+    assert [f.title for f in findings] == golden_titles, (
+        f"finding order mismatch: {[f.title for f in findings]}"
+    )
+
+    # ── Group finding ─────────────────────────────────────────────────────────
+    grp_f = findings[0]
+    # max_ent < 1.8 so MEDIUM (subdomains score 1.77 and 1.70)
+    assert grp_f.severity == Severity.MEDIUM
+
+    expected_grp_ev = {
+        "registrable_domain": "malware.example",
+        "subdomain_count": 2,
+        "max_entropy": round(max(ent_a3f7bc19, ent_m8x2q9n), 4),
+        "min_entropy": round(min(ent_a3f7bc19, ent_m8x2q9n), 4),
+        "total_queries": 2,
+        "unique_sources": 2,
+        "sample_domains": ["a3f7bc19.malware.example", "m8x2q9n.malware.example"],
+        "querier_ips": ["192.0.2.1", "192.0.2.2"],
+    }
+    for key, expected_val in expected_grp_ev.items():
+        assert grp_f.evidence[key] == expected_val, (
+            f"group evidence[{key!r}]: got {grp_f.evidence[key]!r}, expected {expected_val!r}"
+        )
+
+    # source is the ONE permitted additive key in Commit 2
+    assert grp_f.evidence.get("source") == "zeek", (
+        f"expected source='zeek', got {grp_f.evidence.get('source')!r}"
+    )
+    _pre_refactor_grp_keys = {
+        "registrable_domain", "subdomain_count", "max_entropy", "min_entropy",
+        "total_queries", "unique_sources", "sample_domains", "querier_ips",
+    }
+    new_grp_keys = set(grp_f.evidence.keys()) - _pre_refactor_grp_keys
+    assert new_grp_keys == {"source"}, (
+        f"only 'source' may be added to group evidence; unexpected new keys: {new_grp_keys}"
+    )
+
+    # ── Singleton finding ─────────────────────────────────────────────────────
+    sng_f = findings[1]
+    assert sng_f.severity == Severity.HIGH   # 1.93 >= 1.8
+    assert sng_f.title == "k8x2m5q7n1p.suspect.example"
+
+    expected_sng_ev = {
+        "entropy": round(ent_suspect, 4),
+        "query_count": 1,
+        "unique_sources": 1,
+        "querier_ips": ["192.0.2.1"],
+        "rcode_distribution": {},            # no rcode column in fixture
+    }
+    for key, expected_val in expected_sng_ev.items():
+        assert sng_f.evidence[key] == expected_val, (
+            f"singleton evidence[{key!r}]: got {sng_f.evidence[key]!r}, expected {expected_val!r}"
+        )
+    assert sng_f.evidence.get("source") == "zeek", (
+        f"expected source='zeek', got {sng_f.evidence.get('source')!r}"
+    )
+    _pre_refactor_sng_keys = {
+        "entropy", "query_count", "unique_sources", "querier_ips", "rcode_distribution",
+    }
+    new_sng_keys = set(sng_f.evidence.keys()) - _pre_refactor_sng_keys
+    assert new_sng_keys == {"source"}, (
+        f"only 'source' may be added to singleton evidence; unexpected new keys: {new_sng_keys}"
+    )
+
+
+# ── Pihole aggregate tests ────────────────────────────────────────────────────
+
+def test_pihole_aggregate_produces_per_domain_rows(monkeypatch) -> None:
+    """_build_pihole_aggregate produces exactly one row per unique query domain."""
+    import loghunter.detectors.dns as dns_mod
+
+    monkeypatch.setattr(dns_mod.tldextract, "extract", lambda q: SimpleNamespace(
+        domain="example", suffix="com", subdomain=q.split(".")[0],
+        top_domain_under_public_suffix="example.com",
+    ))
+
+    rows = [
+        # alpha — 3 query events from 2 clients + 1 forwarded
+        {"query": "alpha.example.com", "event_type": "query",     "src": "192.0.2.1", "qtype": "A"},
+        {"query": "alpha.example.com", "event_type": "query",     "src": "192.0.2.1", "qtype": "A"},
+        {"query": "alpha.example.com", "event_type": "query",     "src": "192.0.2.2", "qtype": "A"},
+        {"query": "alpha.example.com", "event_type": "forwarded", "src": None,        "qtype": None},
+        # beta — 2 query events from 1 client
+        {"query": "beta.example.com",  "event_type": "query",     "src": "192.0.2.3", "qtype": "AAAA"},
+        {"query": "beta.example.com",  "event_type": "query",     "src": "192.0.2.3", "qtype": "AAAA"},
+        # gamma — 4 query events from 3 clients
+        {"query": "gamma.example.com", "event_type": "query",     "src": "192.0.2.1", "qtype": "A"},
+        {"query": "gamma.example.com", "event_type": "query",     "src": "192.0.2.4", "qtype": "A"},
+        {"query": "gamma.example.com", "event_type": "query",     "src": "192.0.2.5", "qtype": "A"},
+        {"query": "gamma.example.com", "event_type": "query",     "src": "192.0.2.5", "qtype": "A"},
+    ]
+    agg = _build_pihole_aggregate(pd.DataFrame(rows))
+
+    assert len(agg) == 3, f"expected 3 rows, got {len(agg)}"
+
+    alpha = agg[agg["query"] == "alpha.example.com"].iloc[0]
+    assert alpha["query_count"] == 3
+    assert alpha["unique_clients"] == 2
+    # 1 forwarded / 3 query events
+    assert round(float(alpha["forward_ratio"]), 4) == round(1 / 3, 4)
+
+    beta = agg[agg["query"] == "beta.example.com"].iloc[0]
+    assert beta["query_count"] == 2
+    assert beta["unique_clients"] == 1
+
+    gamma = agg[agg["query"] == "gamma.example.com"].iloc[0]
+    assert gamma["query_count"] == 4
+    assert gamma["unique_clients"] == 3
+
+
+def test_pihole_blocked_domain_evidence(monkeypatch) -> None:
+    """A domain with a gravity_blocked event produces was_blocked=True, block_ratio > 0."""
+    import loghunter.detectors.dns as dns_mod
+
+    monkeypatch.setattr(dns_mod.tldextract, "extract", lambda q: SimpleNamespace(
+        domain="example", suffix="com", subdomain="blocked",
+        top_domain_under_public_suffix="example.com",
+    ))
+
+    rows = [
+        {"query": "blocked.example.com", "event_type": "query",           "src": "192.0.2.1", "qtype": "A"},
+        {"query": "blocked.example.com", "event_type": "query",           "src": "192.0.2.1", "qtype": "A"},
+        {"query": "blocked.example.com", "event_type": "gravity_blocked", "src": None,        "qtype": None},
+    ]
+    agg = _build_pihole_aggregate(pd.DataFrame(rows))
+
+    assert len(agg) == 1
+    row = agg.iloc[0]
+    assert bool(row["was_blocked"]) is True
+    assert row["block_ratio"] > 0
+    # block_count=1, total_count=3, block_ratio=1/3
+    assert round(float(row["block_ratio"]), 4) == round(1 / 3, 4)
+
+
+def test_block_ratio_union_gravity_and_regex(monkeypatch) -> None:
+    """block_count collapses gravity_blocked + regex_blocked (not counted separately)."""
+    import loghunter.detectors.dns as dns_mod
+
+    monkeypatch.setattr(dns_mod.tldextract, "extract", lambda q: SimpleNamespace(
+        domain="example", suffix="com", subdomain="evil",
+        top_domain_under_public_suffix="example.com",
+    ))
+
+    rows = [
+        {"query": "evil.example.com", "event_type": "query",           "src": "192.0.2.1", "qtype": "A"},
+        {"query": "evil.example.com", "event_type": "query",           "src": "192.0.2.1", "qtype": "A"},
+        {"query": "evil.example.com", "event_type": "gravity_blocked", "src": None,        "qtype": None},
+        {"query": "evil.example.com", "event_type": "gravity_blocked", "src": None,        "qtype": None},
+        {"query": "evil.example.com", "event_type": "regex_blocked",   "src": None,        "qtype": None},
+    ]
+    agg = _build_pihole_aggregate(pd.DataFrame(rows))
+
+    assert len(agg) == 1
+    row = agg.iloc[0]
+    assert int(row["block_count"]) == 3, "gravity_blocked (2) + regex_blocked (1) must sum to 3"
+    # total_count=5, block_ratio=3/5=0.6
+    assert round(float(row["block_ratio"]), 4) == round(3 / 5, 4)
+
+
+def test_block_ratio_not_in_pihole_feature_matrix() -> None:
+    """Evidence-only columns must not appear in the pihole feature matrix."""
+    agg_df = pd.DataFrame([
+        {
+            "query": "sub1.example.com",
+            "query_count": 5, "forward_count": 2, "cache_count": 1,
+            "block_count": 0, "special_count": 0, "total_count": 8,
+            "unique_clients": 2, "unique_qtypes": 1,
+            "querier_ips": ["192.0.2.1", "192.0.2.2"],
+            "qtype_counts": {"A": 5},
+            "forward_ratio": 0.4, "cache_ratio": 0.2,
+            "block_ratio": 0.0, "was_blocked": False,
+            "unique_sources": 2,
+        },
+        {
+            "query": "sub2.example.net",
+            "query_count": 3, "forward_count": 1, "cache_count": 0,
+            "block_count": 1, "special_count": 0, "total_count": 4,
+            "unique_clients": 1, "unique_qtypes": 2,
+            "querier_ips": ["192.0.2.3"],
+            "qtype_counts": {"A": 2, "AAAA": 1},
+            "forward_ratio": 0.333, "cache_ratio": 0.0,
+            "block_ratio": 0.25, "was_blocked": True,
+            "unique_sources": 1,
+        },
+    ])
+
+    feat = _build_pihole_features(agg_df)
+
+    for col in ("block_ratio", "was_blocked", "block_count", "forward_count",
+                "cache_count", "total_count", "special_count"):
+        assert col not in feat.columns, f"{col!r} must not appear in pihole feature matrix"
+
+
+# ── Both-mode (Zeek + pihole) tests ──────────────────────────────────────────
+
+# Shared fixture for both-mode tests.
+# After degenerate filter, dns_df has 3 rows: safe→cluster 0, normal→cluster 0, noise.
+# FakeHDBSCAN3 assigns [0, 0, -1] so a3f7bc19.example.com is the noise domain.
+_BOTH_MODE_ZEEK_EXT = {
+    "safe.example.com":     SimpleNamespace(domain="example", suffix="com", subdomain="safe",     top_domain_under_public_suffix="example.com"),
+    "normal.example.net":   SimpleNamespace(domain="example", suffix="net", subdomain="normal",   top_domain_under_public_suffix="example.net"),
+    "a3f7bc19.example.com": SimpleNamespace(domain="example", suffix="com", subdomain="a3f7bc19", top_domain_under_public_suffix="example.com"),
+}
+
+_BOTH_MODE_ZEEK_DF = pd.DataFrame([
+    {"ts": 1.0, "src": "192.0.2.1", "query": "safe.example.com"},
+    {"ts": 2.0, "src": "192.0.2.2", "query": "normal.example.net"},
+    {"ts": 3.0, "src": "192.0.2.1", "query": "a3f7bc19.example.com"},
+])
+
+_BOTH_MODE_PIHOLE_DF = pd.DataFrame([
+    {"ts": 4.0, "src": None,        "query": "a3f7bc19.example.com", "event_type": "gravity_blocked", "qtype": None},
+    {"ts": 5.0, "src": "192.0.2.1", "query": "a3f7bc19.example.com", "event_type": "query",           "qtype": "A"},
+])
+
+
+class _FakeHDBSCAN3:
+    def __init__(self, **kwargs): pass
+    def fit_predict(self, X: np.ndarray) -> np.ndarray:
+        return np.array([0, 0, -1])
+
+
+def test_both_mode_zeek_enriched_with_pihole_block(monkeypatch) -> None:
+    """Both-mode: Zeek noise domain enriched with pihole block data carries was_blocked in evidence."""
+    import loghunter.detectors.dns as dns_mod
+
+    monkeypatch.setattr(dns_mod.tldextract, "extract", lambda q: _BOTH_MODE_ZEEK_EXT.get(
+        q, SimpleNamespace(domain="", suffix="", subdomain="", top_domain_under_public_suffix=""),
+    ))
+    monkeypatch.setattr(clustering, "HDBSCAN", _FakeHDBSCAN3)
+
+    ctx = DetectorContext(
+        logs={"dns*.log*": _BOTH_MODE_ZEEK_DF.copy(), "pihole*.log*": _BOTH_MODE_PIHOLE_DF.copy()},
+        config={"min_cluster_size": 3, "min_samples": 1, "threshold": 1.5, "thresh_high_entropy": 1.8},
+        allowlist=None,
+        data_window=_WINDOW,
+    )
+    findings = run(ctx)
+
+    assert len(findings) >= 1, "expected at least one finding from both-mode run"
+    f = findings[0]
+    assert f.evidence["source"] == "zeek"
+    assert f.evidence.get("was_blocked") is True, "noise domain blocked by pihole must carry was_blocked=True"
+    assert f.evidence.get("block_ratio", 0.0) > 0.0, "block_ratio must be > 0 for a blocked domain"
+
+
+def test_both_mode_pihole_not_independently_clustered(monkeypatch) -> None:
+    """Both-mode: pihole data enriches Zeek; no independent pihole clustering happens."""
+    import loghunter.detectors.dns as dns_mod
+
+    monkeypatch.setattr(dns_mod.tldextract, "extract", lambda q: _BOTH_MODE_ZEEK_EXT.get(
+        q, SimpleNamespace(domain="", suffix="", subdomain="", top_domain_under_public_suffix=""),
+    ))
+    monkeypatch.setattr(clustering, "HDBSCAN", _FakeHDBSCAN3)
+
+    ctx = DetectorContext(
+        logs={"dns*.log*": _BOTH_MODE_ZEEK_DF.copy(), "pihole*.log*": _BOTH_MODE_PIHOLE_DF.copy()},
+        config={"min_cluster_size": 3, "min_samples": 1, "threshold": 1.5, "thresh_high_entropy": 1.8},
+        allowlist=None,
+        data_window=_WINDOW,
+    )
+    findings = run(ctx)
+
+    assert all(f.evidence.get("source") != "pihole" for f in findings), (
+        "both-mode must only produce zeek findings — no independent pihole clustering"
+    )
+
+
+# ── Pihole event-type exclusion tests ────────────────────────────────────────
+
+def test_excluded_event_types_not_in_aggregation(monkeypatch) -> None:
+    """dnssec_query, dhcp, and pihole_hostname must not contribute to query_count."""
+    import loghunter.detectors.dns as dns_mod
+
+    monkeypatch.setattr(dns_mod.tldextract, "extract", lambda q: SimpleNamespace(
+        domain="example", suffix="com", subdomain="target",
+        top_domain_under_public_suffix="example.com",
+    ))
+
+    rows = [
+        # 3 query events that SHOULD count
+        {"query": "target.example.com", "event_type": "query",           "src": "192.0.2.1", "qtype": "A"},
+        {"query": "target.example.com", "event_type": "query",           "src": "192.0.2.1", "qtype": "A"},
+        {"query": "target.example.com", "event_type": "query",           "src": "192.0.2.2", "qtype": "A"},
+        # excluded event types
+        {"query": "target.example.com", "event_type": "dnssec_query",    "src": None, "qtype": "DS"},
+        {"query": "target.example.com", "event_type": "dnssec_query",    "src": None, "qtype": "DNSKEY"},
+        {"query": "target.example.com", "event_type": "dhcp",            "src": None, "qtype": None},
+        {"query": "target.example.com", "event_type": "pihole_hostname", "src": None, "qtype": None},
+    ]
+    agg = _build_pihole_aggregate(pd.DataFrame(rows))
+
+    assert len(agg) == 1
+    assert agg.iloc[0]["query_count"] == 3, "only query events should count in query_count"
+
+
+def test_special_not_in_cluster_features_but_in_evidence(monkeypatch) -> None:
+    """special events count as annotation in aggregate but must not enter the feature matrix."""
+    import loghunter.detectors.dns as dns_mod
+
+    monkeypatch.setattr(dns_mod.tldextract, "extract", lambda q: SimpleNamespace(
+        domain="example", suffix="com", subdomain="relay",
+        top_domain_under_public_suffix="example.com",
+    ))
+
+    rows = [
+        {"query": "relay.example.com", "event_type": "query",   "src": "192.0.2.1", "qtype": "A"},
+        {"query": "relay.example.com", "event_type": "query",   "src": "192.0.2.1", "qtype": "A"},
+        {"query": "relay.example.com", "event_type": "query",   "src": "192.0.2.2", "qtype": "A"},
+        {"query": "relay.example.com", "event_type": "special", "src": None,        "qtype": None},
+        {"query": "relay.example.com", "event_type": "special", "src": None,        "qtype": None},
+    ]
+    agg = _build_pihole_aggregate(pd.DataFrame(rows))
+
+    assert len(agg) == 1
+    assert int(agg.iloc[0]["special_count"]) == 2, "special events must be counted in aggregate"
+
+    feat = _build_pihole_features(agg)
+    assert "special_count" not in feat.columns, "special_count must not enter the feature matrix"
+
+
+# ── Pihole-only end-to-end test ───────────────────────────────────────────────
+
+_PIHOLE_ONLY_EXT = {
+    "a3f7bc19.sus1.example":    SimpleNamespace(domain="sus1", suffix="example", subdomain="a3f7bc19",    top_domain_under_public_suffix="sus1.example"),
+    "m8x2q9n.sus2.example":     SimpleNamespace(domain="sus2", suffix="example", subdomain="m8x2q9n",     top_domain_under_public_suffix="sus2.example"),
+    "k8x2m5q7n1p.sus3.example": SimpleNamespace(domain="sus3", suffix="example", subdomain="k8x2m5q7n1p", top_domain_under_public_suffix="sus3.example"),
+}
+
+
+def test_pihole_only_run_produces_findings(monkeypatch) -> None:
+    """pihole-only run returns findings with source='pihole' for all entries."""
+    import loghunter.detectors.dns as dns_mod
+
+    monkeypatch.setattr(dns_mod.tldextract, "extract", lambda q: _PIHOLE_ONLY_EXT.get(
+        q, SimpleNamespace(domain="", suffix="", subdomain="", top_domain_under_public_suffix=""),
+    ))
+
+    class _FakeAllNoise:
+        def __init__(self, **kwargs): pass
+        def fit_predict(self, X: np.ndarray) -> np.ndarray:
+            return np.full(len(X), -1, dtype=int)
+
+    monkeypatch.setattr(clustering, "HDBSCAN", _FakeAllNoise)
+
+    rows = []
+    for domain in _PIHOLE_ONLY_EXT:
+        for i in range(3):
+            rows.append({"query": domain, "event_type": "query", "src": f"192.0.2.{i + 1}", "qtype": "A"})
+    pihole_df = pd.DataFrame(rows)
+
+    ctx = DetectorContext(
+        logs={"pihole*.log*": pihole_df},
+        config={
+            "threshold": 1.5,
+            "thresh_high_entropy": 1.8,
+            "pihole": {"min_cluster_size": 2, "min_samples": 1},
+        },
+        allowlist=None,
+        data_window=_WINDOW,
+    )
+    findings = run(ctx)
+
+    assert isinstance(findings, list)
+    assert len(findings) >= 1, "pihole-only run should produce at least one finding"
+    assert all(f.evidence.get("source") == "pihole" for f in findings), (
+        "all findings from a pihole-only run must carry source='pihole'"
+    )
+
+
+# ── _shared_back_half grouping ────────────────────────────────────────────────
+
+def test_shared_back_half_grouping_consistency() -> None:
+    """Two candidate rows sharing the same registrable domain produce one group finding."""
+    candidate_df = pd.DataFrame([
+        {
+            "query": "a3f7bc19.example.com",
+            "label_entropy": 1.77,
+            "registrable_domain": "example.com",
+            "unique_sources": 1,
+            "querier_ips": ["192.0.2.1"],
+            "source": "pihole",
+            "query_count": 5,
+            "was_blocked": False,
+            "block_ratio": 0.0,
+            "cache_ratio": 0.2,
+            "forward_ratio": 0.8,
+            "qtype_counts": {"A": 5},
+            "special_count": 0,
+        },
+        {
+            "query": "m8x2q9n.example.com",
+            "label_entropy": 1.70,
+            "registrable_domain": "example.com",
+            "unique_sources": 1,
+            "querier_ips": ["192.0.2.2"],
+            "source": "pihole",
+            "query_count": 3,
+            "was_blocked": False,
+            "block_ratio": 0.0,
+            "cache_ratio": 0.3,
+            "forward_ratio": 0.7,
+            "qtype_counts": {"A": 3},
+            "special_count": 0,
+        },
+    ])
+
+    findings = _shared_back_half(candidate_df, threshold=1.5, thresh_high=1.8, now=_NOW, data_window=_WINDOW)
+
+    assert len(findings) == 1, "two rows with same registrable domain must produce one group finding"
+    assert findings[0].evidence["subdomain_count"] == 2
+    assert findings[0].evidence["source"] == "pihole"
+
+
+def test_pihole_group_qtype_counts_aggregated() -> None:
+    """pihole group finding aggregates qtype_counts across all member rows."""
+    candidate_df = pd.DataFrame([
+        {
+            "query": "a3f7bc19.example.com",
+            "label_entropy": 1.77,
+            "registrable_domain": "example.com",
+            "unique_sources": 1,
+            "querier_ips": ["192.0.2.1"],
+            "source": "pihole",
+            "query_count": 5,
+            "was_blocked": False,
+            "block_ratio": 0.0,
+            "cache_ratio": 0.2,
+            "forward_ratio": 0.8,
+            "qtype_counts": {"A": 4, "AAAA": 1},
+            "special_count": 0,
+        },
+        {
+            "query": "m8x2q9n.example.com",
+            "label_entropy": 1.70,
+            "registrable_domain": "example.com",
+            "unique_sources": 1,
+            "querier_ips": ["192.0.2.2"],
+            "source": "pihole",
+            "query_count": 3,
+            "was_blocked": False,
+            "block_ratio": 0.0,
+            "cache_ratio": 0.3,
+            "forward_ratio": 0.7,
+            "qtype_counts": {"A": 2, "HTTPS": 1},
+            "special_count": 0,
+        },
+    ])
+
+    findings = _shared_back_half(candidate_df, threshold=1.5, thresh_high=1.8, now=_NOW, data_window=_WINDOW)
+
+    assert len(findings) == 1
+    qtypes = findings[0].evidence.get("qtype_counts")
+    assert isinstance(qtypes, dict), "group finding must have qtype_counts dict"
+    assert qtypes.get("A") == 6, f"A count should be 4+2=6, got {qtypes.get('A')}"
+    assert qtypes.get("AAAA") == 1, f"AAAA count should be 1, got {qtypes.get('AAAA')}"
+    assert qtypes.get("HTTPS") == 1, f"HTTPS count should be 1, got {qtypes.get('HTTPS')}"
+
+
+# ── Null/invalid query guard ──────────────────────────────────────────────────
+
+def test_pihole_aggregate_null_query_rows_ignored(monkeypatch) -> None:
+    """Rows with query=None, query='', or query=<non-string> are silently dropped."""
+    import loghunter.detectors.dns as dns_mod
+
+    monkeypatch.setattr(dns_mod.tldextract, "extract", lambda q: SimpleNamespace(
+        domain="example", suffix="com", subdomain="api",
+        top_domain_under_public_suffix="example.com",
+    ))
+
+    rows = [
+        {"query": "api.example.com", "event_type": "query", "src": "192.0.2.1", "qtype": "A"},
+        {"query": None,               "event_type": "query", "src": "192.0.2.1", "qtype": "A"},
+        {"query": "",                 "event_type": "query", "src": "192.0.2.1", "qtype": "A"},
+        {"query": 123,                "event_type": "query", "src": "192.0.2.1", "qtype": "A"},
+    ]
+    agg = _build_pihole_aggregate(pd.DataFrame(rows))
+
+    assert len(agg) == 1, f"expected 1 valid row, got {len(agg)}"
+    assert agg.iloc[0]["query"] == "api.example.com"
+
+
+# ── Partial pihole config override ───────────────────────────────────────────
+
+def test_pihole_cfg_partial_override_keeps_defaults(monkeypatch) -> None:
+    """Partial pihole config override preserves unspecified defaults."""
+    import loghunter.detectors.dns as dns_mod
+
+    captured: dict = {}
+
+    def _spy_run_pihole_path(pihole_df: pd.DataFrame, pihole_cfg: dict) -> None:
+        captured["pihole_cfg"] = dict(pihole_cfg)
+        return None
+
+    monkeypatch.setattr(dns_mod, "_run_pihole_path", _spy_run_pihole_path)
+
+    pihole_df = pd.DataFrame([
+        {"ts": 1.0, "src": "192.0.2.1", "query": "api.example.com", "event_type": "query", "qtype": "A"},
+    ])
+    ctx = DetectorContext(
+        logs={"pihole*.log*": pihole_df},
+        config={"pihole": {"min_samples": 3}},
+        allowlist=None,
+        data_window=_WINDOW,
+    )
+    run(ctx)
+
+    assert "pihole_cfg" in captured, "_run_pihole_path was not called"
+    assert captured["pihole_cfg"]["min_cluster_size"] == DEFAULT_CONFIG["pihole"]["min_cluster_size"], (
+        "min_cluster_size must fall back to DEFAULT_CONFIG when not overridden"
+    )
+    assert captured["pihole_cfg"]["min_samples"] == 3, "min_samples must be taken from user config"
+
+
+# ── _enrich_zeek_with_pihole: no-match defaults ───────────────────────────────
+
+def test_both_mode_no_pihole_match_block_ratio_is_zero() -> None:
+    """Zeek domains with no pihole match get block_ratio=0.0, was_blocked=False (never NaN)."""
+    dns_df = pd.DataFrame([
+        {"ts": 1.0, "src": "192.0.2.1", "query": "sub.example.com"},
+        {"ts": 2.0, "src": "192.0.2.2", "query": "api.example.com"},
+    ])
+    pihole_df = pd.DataFrame([
+        {"ts": 3.0, "src": None, "query": "other.unrelated.example", "event_type": "gravity_blocked", "qtype": None},
+    ])
+
+    result = _enrich_zeek_with_pihole(dns_df.copy(), pihole_df)
+
+    assert "block_ratio" in result.columns
+    assert "was_blocked" in result.columns
+    assert (result["block_ratio"] == 0.0).all(), "unmatched domains must have block_ratio=0.0"
+    assert (result["was_blocked"] == False).all(), "unmatched domains must have was_blocked=False"
+    assert not result["block_ratio"].isna().any(), "block_ratio must never be NaN"
+
+
+# ── Text renderer tests ───────────────────────────────────────────────────────
+
+def _make_dns_finding(severity: Severity, title: str, evidence: dict) -> Finding:
+    return Finding(
+        detector="dns",
+        severity=severity,
+        title=title,
+        description="test description",
+        evidence=evidence,
+        next_steps=[],
+        ts_generated=_NOW,
+        data_window=_WINDOW,
+    )
+
+
+def test_text_renderer_pihole_default_shows_blocked() -> None:
+    """Pihole singleton with was_blocked=True shows BLOCKED token in default output."""
+    f = _make_dns_finding(
+        Severity.HIGH,
+        "a3f7bc19.example.com",
+        {
+            "source": "pihole",
+            "entropy": 1.77,
+            "query_count": 5,
+            "unique_sources": 2,
+            "querier_ips": ["192.0.2.1"],
+            "was_blocked": True,
+            "block_ratio": 0.5,
+            "cache_ratio": 0.2,
+            "forward_ratio": 0.3,
+            "qtype_counts": {"A": 5},
+            "special_count": 0,
+        },
+    )
+    handler = TextHandler(verbose_level=0)
+    lines = handler._render_dns_group(_dns_sections([f]))
+    output = "\n".join(lines)
+    assert "BLOCKED" in output, "was_blocked=True must show BLOCKED token in default output"
+
+
+def test_text_renderer_pihole_default_no_blocked_marker() -> None:
+    """Pihole singleton with was_blocked=False omits BLOCKED token from default output."""
+    f = _make_dns_finding(
+        Severity.MEDIUM,
+        "sub.example.com",
+        {
+            "source": "pihole",
+            "entropy": 1.55,
+            "query_count": 3,
+            "unique_sources": 1,
+            "querier_ips": ["192.0.2.1"],
+            "was_blocked": False,
+            "block_ratio": 0.0,
+            "cache_ratio": 0.4,
+            "forward_ratio": 0.6,
+            "qtype_counts": {"A": 3},
+            "special_count": 0,
+        },
+    )
+    handler = TextHandler(verbose_level=0)
+    lines = handler._render_dns_group(_dns_sections([f]))
+    output = "\n".join(lines)
+    assert "BLOCKED" not in output, "was_blocked=False must not show BLOCKED token"
+
+
+def test_text_renderer_pihole_verbose_shows_ratios() -> None:
+    """Pihole singleton verbose output shows block/cache/fwd ratios; no rcode lines."""
+    f = _make_dns_finding(
+        Severity.HIGH,
+        "a3f7bc19.example.com",
+        {
+            "source": "pihole",
+            "entropy": 1.77,
+            "query_count": 5,
+            "unique_sources": 2,
+            "querier_ips": ["192.0.2.1"],
+            "was_blocked": True,
+            "block_ratio": 0.5,
+            "cache_ratio": 0.2,
+            "forward_ratio": 0.3,
+            "qtype_counts": {"A": 5},
+            "special_count": 0,
+        },
+    )
+    handler = TextHandler(verbose_level=1)
+    lines = handler._render_dns_group(_dns_sections([f]))
+    output = "\n".join(lines)
+
+    # W3 curated tail surfaces ratios as raw key:value pairs (no percent
+    # formatting in the uniform evidence block — see GLENN notes).
+    assert "block_ratio: 0.5" in output, "block_ratio must appear in verbose output"
+    assert "was_blocked: True" in output, "was_blocked must appear in verbose output"
+    # Pihole's qtype_counts is part of the pihole curated subset.
+    assert "qtype_counts" in output, "qtype_counts must appear in pihole verbose"
+    assert "rcode_distribution" not in output, "pihole verbose must not show rcode_distribution"
+
+
+def test_text_renderer_zeek_default_line_unchanged() -> None:
+    """Zeek-only singletons produce the character-identical pre-pihole format (no BLOCKED column)."""
+    f1 = _make_dns_finding(
+        Severity.HIGH,
+        "sub.example.com",
+        {
+            "source": "zeek",
+            "entropy": 2.10,
+            "query_count": 5,
+            "unique_sources": 2,
+            "querier_ips": ["192.0.2.1"],
+            "rcode_distribution": {},
+        },
+    )
+    f2 = _make_dns_finding(
+        Severity.HIGH,
+        "api.example.net",
+        {
+            "source": "zeek",
+            "entropy": 1.92,
+            "query_count": 3,
+            "unique_sources": 1,
+            "querier_ips": ["192.0.2.2"],
+            "rcode_distribution": {},
+        },
+    )
+    handler = TextHandler(verbose_level=0)
+    lines = handler._render_dns_group(_dns_sections([f1, f2]))
+
+    # Analytically derive expected strings — column widths are max across both rows:
+    # ent_w=8 ("ent=2.10"), qry_w=5 ("5 qry"), src_w=5 ("2 src"), blocked_w=0 (no blocked)
+    tag = f"{'[H]':<4}"  # "[H] "
+    expected_1 = f"  {tag}  {'ent=2.10':<8}  {'5 qry':>5}  {'2 src':>5}  sub.example.com"
+    expected_2 = f"  {tag}  {'ent=1.92':<8}  {'3 qry':>5}  {'1 src':>5}  api.example.net"
+
+    # Row lines start with the 2-space indent + severity tag. Skip the
+    # subsection label (e.g. "singletons (2)") and any blank lines.
+    singleton_lines = [l for l in lines if l.startswith("  [")]
+    assert singleton_lines[0] == expected_1, (
+        f"line 1 mismatch:\n  got:      {singleton_lines[0]!r}\n  expected: {expected_1!r}"
+    )
+    assert singleton_lines[1] == expected_2, (
+        f"line 2 mismatch:\n  got:      {singleton_lines[1]!r}\n  expected: {expected_2!r}"
+    )
+    assert "BLOCKED" not in "\n".join(lines), "Zeek-only output must not contain BLOCKED token"
+
+
+def test_text_renderer_dns_sections_have_breathing_room() -> None:
+    """DNS output separates detector and subgroup sections with blank lines."""
+    singleton = _make_dns_finding(
+        Severity.HIGH,
+        "a3f7bc19.example.com",
+        {
+            "source": "pihole",
+            "entropy": 1.77,
+            "query_count": 5,
+            "unique_sources": 1,
+            "querier_ips": ["192.0.2.1"],
+            "was_blocked": False,
+            "block_ratio": 0.0,
+            "cache_ratio": 0.2,
+            "forward_ratio": 0.8,
+            "qtype_counts": {"A": 5},
+            "special_count": 0,
+        },
+    )
+    group = _make_dns_finding(
+        Severity.MEDIUM,
+        "example.com (2 subdomains, entropy >= 1.8)",
+        {
+            "source": "pihole",
+            "registrable_domain": "example.com",
+            "subdomain_count": 2,
+            "max_entropy": 1.77,
+            "min_entropy": 1.7,
+            "total_queries": 8,
+            "unique_sources": 2,
+            "sample_domains": ["a3f7bc19.example.com", "m8x2q9n.example.com"],
+            "querier_ips": ["192.0.2.1", "192.0.2.2"],
+            "was_blocked": False,
+            "block_ratio": 0.0,
+            "cache_ratio": 0.2,
+            "forward_ratio": 0.8,
+            "qtype_counts": {"A": 8},
+            "special_count": 0,
+        },
+    )
+
+    lines = TextHandler(verbose_level=0)._render_dns_group(_dns_sections([singleton, group]))
+
+    # The detector-level blank line above the singletons subsection is emitted
+    # by TextHandler.write (`print(file=stream)` before the header rule), not
+    # by the renderer itself. Inside the renderer's output we only see the
+    # gap BETWEEN sections.
+    group_header = next(i for i, line in enumerate(lines) if "groups" in line)
+    assert lines[group_header - 1] == ""
+
+
+def test_text_renderer_zeek_verbose_rcode_unchanged() -> None:
+    """Zeek singleton verbose output shows rcodes: line; no ratio lines."""
+    f = _make_dns_finding(
+        Severity.HIGH,
+        "sub.example.com",
+        {
+            "source": "zeek",
+            "entropy": 1.92,
+            "query_count": 6,
+            "unique_sources": 2,
+            "querier_ips": ["192.0.2.1"],
+            "rcode_distribution": {"NOERROR": 5, "NXDOMAIN": 1},
+        },
+    )
+    handler = TextHandler(verbose_level=1)
+    lines = handler._render_dns_group(_dns_sections([f]))
+    output = "\n".join(lines)
+
+    # W3 curated tail: zeek singleton surfaces rcode_distribution as a raw
+    # key:value pair (no per-detector ratio formatting).
+    assert "rcode_distribution" in output, "Zeek verbose must show rcode_distribution"
+    assert "NOERROR" in output, "rcode keys must appear"
+    assert "block_ratio" not in output, "Zeek-only verbose must not show block_ratio"
+
+
+def test_text_renderer_both_mode_verbose_shows_was_blocked() -> None:
+    """Both-mode Zeek singleton with was_blocked=True shows was_blocked annotation in verbose."""
+    f = _make_dns_finding(
+        Severity.HIGH,
+        "a3f7bc19.example.com",
+        {
+            "source": "zeek",
+            "entropy": 1.77,
+            "query_count": 3,
+            "unique_sources": 1,
+            "querier_ips": ["192.0.2.1"],
+            "rcode_distribution": {},
+            "was_blocked": True,
+            "block_ratio": 0.5,
+        },
+    )
+    handler = TextHandler(verbose_level=1)
+    lines = handler._render_dns_group(_dns_sections([f]))
+    output = "\n".join(lines)
+
+    # W3 curated tail: both-mode (Zeek + Pi-hole enrichment) surfaces
+    # was_blocked + block_ratio as raw key:value pairs. The "(Pi-hole
+    # enrichment)" prose annotation from the old per-detector block is gone
+    # — the keys themselves carry the provenance (a Zeek finding doesn't
+    # have was_blocked otherwise).
+    assert "was_blocked: True" in output, "both-mode verbose must show was_blocked"
+    assert "block_ratio: 0.5" in output, "block_ratio must appear in both-mode verbose"