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

loghunter/parsers/__init__.py

@@ -0,0 +1 @@
+"""Parser modules for normalizing local log formats before detector analysis."""

loghunter/parsers/cloudtrail.py

@@ -0,0 +1,287 @@
+"""CloudTrail event parsing — normalize raw AWS events into canonical row dicts.
+
+Provides pure parsing functions with no file I/O. File discovery, decompression,
+NDJSON / envelope sniffing, DataFrame construction, and timeframe filtering are
+handled by loader.py via load_cloudtrail().
+
+Per-event normalization, not aggregation. The aws detector aggregates per-principal
+on the back end — the same parser-emits-fragments / detector-aggregates split that
+dnsmasq uses (`_build_pihole_aggregate` lives in the detector, not the parser).
+
+Canonical CloudTrail event schema (v1)
+──────────────────────────────────────
+parse_event() emits one dict per event with these twelve keys, all always present.
+
+Carried fields (verbatim from the wire event, or None when absent):
+  ts            — eventTime parsed to unix epoch float; None when missing/garbage
+  event_source  — eventSource (full string, e.g. "s3.amazonaws.com")
+  event_name    — eventName (e.g. "ListBuckets")
+  identity_type — userIdentity.type (IAMUser, AssumedRole, AWSService, Root, …)
+  source_ip     — sourceIPAddress
+  error_code    — errorCode; None means the call succeeded
+  aws_region    — awsRegion — human-triage pivot
+  event_id      — eventID — drill-back anchor; the analyst's key to the full event
+
+Derived fields (computed from one or more wire fields by the rules below):
+  principal     — stable per-actor key; collapses userIdentity variants so a role
+                  assumed many times is one actor, not many. See _derive_principal.
+  lane          — "interactive" | "service", mechanically derived from
+                  userIdentity.type / invokedBy / service-linked-role naming
+  read_write    — "read" | "write"; top-level readOnly when present, else inferred
+                  from the action verb (handles thinner old event schemas)
+
+Escape hatch (SCHEMA.md → promote-don't-grep):
+  raw           — original event dict, unmodified. No v1 detector reads this at
+                  runtime. Future detectors that need fields living in `raw` —
+                  recipient_account_id, user_agent, requestParameters,
+                  responseElements, resources — promote them to real, typed,
+                  documented canonical columns at that time, with real knowledge
+                  of what the signal needs. Detectors never reach into `raw`
+                  mid-analysis.
+
+Adding a carried column later is a one-line, obvious change: add the key to the
+single result-dict literal in parse_event(), pulled with .get(...).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from datetime import datetime
+from typing import Any
+
+# Verb-inference fallback for read_write — used only when an event has no top-level
+# readOnly field (older CloudTrail event schemas). A prefix match in this set maps
+# the event to "read"; everything else is "write".
+_READ_VERB_PREFIXES: tuple[str, ...] = (
+    "Get", "List", "Describe", "Head", "Lookup",
+    "Search", "BatchGet", "Select", "Query", "Scan",
+)
+
+
+def parse_event(event: Any) -> dict | None:
+    """Parse a raw CloudTrail event dict into the canonical row dict.
+
+    Returns None only when ``event`` is not a dict. For any dict input, returns
+    a row with all twelve canonical keys present — never raises on missing,
+    malformed, or unexpected fields anywhere in the event. All sub-lookups are
+    defensive: missing nested objects degrade to the appropriate field-level
+    fallback rather than aborting the parse.
+    """
+    if not isinstance(event, dict):
+        return None
+
+    user_identity = event.get("userIdentity")
+    identity_type = user_identity.get("type") if isinstance(user_identity, dict) else None
+
+    return {
+        "ts":            _parse_event_time(event.get("eventTime")),
+        "principal":     _derive_principal(user_identity),
+        "lane":          _derive_lane(user_identity),
+        "read_write":    _derive_read_write(event),
+        "event_source":  event.get("eventSource"),
+        "event_name":    event.get("eventName"),
+        "identity_type": identity_type,
+        "source_ip":     event.get("sourceIPAddress"),
+        "error_code":    event.get("errorCode"),
+        "aws_region":    event.get("awsRegion"),
+        "event_id":      event.get("eventID"),
+        "raw":           event,
+    }
+
+
+# ── Derivation helpers ────────────────────────────────────────────────────────
+
+def _parse_event_time(s: Any) -> float | None:
+    """Parse an ISO 8601 eventTime string to unix epoch float; None on failure.
+
+    Mirrors exporters/cloudtrail.py:_parse_event_time. CloudTrail emits "Z" suffix
+    UTC; fromisoformat handles a "+00:00" offset, hence the substitution.
+    """
+    if not isinstance(s, str) or not s:
+        return None
+    try:
+        return datetime.fromisoformat(s.replace("Z", "+00:00")).timestamp()
+    except (ValueError, TypeError):
+        return None
+
+
+def _derive_principal(user_identity: Any) -> str:
+    """Derive a stable per-actor key from userIdentity.
+
+    Load-bearing intent: a role assumed many times is one actor. AssumedRole events
+    key on the session *issuer*, not the per-assumption session name, so every
+    session of one role aggregates together. See SCHEMA.md for the full rule.
+    """
+    if not isinstance(user_identity, dict):
+        return "unknown"
+
+    itype = user_identity.get("type")
+
+    if itype == "AssumedRole":
+        session_context = user_identity.get("sessionContext")
+        if isinstance(session_context, dict):
+            issuer = session_context.get("sessionIssuer")
+            if isinstance(issuer, dict):
+                user_name = issuer.get("userName")
+                if isinstance(user_name, str) and user_name:
+                    return user_name
+                arn = issuer.get("arn")
+                if isinstance(arn, str) and arn:
+                    last = arn.rsplit("/", 1)[-1]
+                    if last:
+                        return last
+                issuer_pid = issuer.get("principalId")
+                if isinstance(issuer_pid, str) and issuer_pid:
+                    return issuer_pid
+        # fall through to generic fallback when sessionIssuer is absent/empty
+
+    elif itype == "IAMUser":
+        user_name = user_identity.get("userName")
+        if isinstance(user_name, str) and user_name:
+            return user_name
+        arn = user_identity.get("arn")
+        if isinstance(arn, str) and arn:
+            last = arn.rsplit("/", 1)[-1]
+            if last:
+                return last
+        # principalId is the next step, handled by the generic fallback below
+
+    elif itype == "AWSService":
+        invoked_by = user_identity.get("invokedBy")
+        if isinstance(invoked_by, str) and invoked_by:
+            return invoked_by
+        # fall through to generic fallback
+
+    elif itype == "Root":
+        return "root"
+
+    # Generic fallback: federated/SAML/WebIdentity/IdentityCenter/AWSAccount/unknown
+    # types, plus fall-through from the per-type branches above when their preferred
+    # fields are missing. principalId stability is what keeps two distinct actors
+    # under an unknown type from collapsing into one bucket.
+    pid = user_identity.get("principalId")
+    if isinstance(pid, str) and pid:
+        return pid
+    if isinstance(itype, str) and itype:
+        return itype
+    return "unknown"
+
+
+def _derive_lane(user_identity: Any) -> str:
+    """Return "service" or "interactive" for an event's userIdentity.
+
+    Mechanical, no security judgment. "service" if any of:
+      1. userIdentity.type is AWSService or AWSAccount
+      2. userIdentity.invokedBy ends with "amazonaws.com"
+      3. "AWSServiceRoleFor" appears in userIdentity.arn or
+         sessionContext.sessionIssuer.arn
+
+    Otherwise "interactive". No hardcoded principal-name list — corpus-specific
+    role names are not a parser concern.
+    """
+    if not isinstance(user_identity, dict):
+        return "interactive"
+
+    itype = user_identity.get("type")
+    if itype in ("AWSService", "AWSAccount"):
+        return "service"
+
+    invoked_by = user_identity.get("invokedBy")
+    if isinstance(invoked_by, str) and invoked_by.endswith("amazonaws.com"):
+        return "service"
+
+    arn = user_identity.get("arn")
+    if isinstance(arn, str) and "AWSServiceRoleFor" in arn:
+        return "service"
+
+    session_context = user_identity.get("sessionContext")
+    if isinstance(session_context, dict):
+        issuer = session_context.get("sessionIssuer")
+        if isinstance(issuer, dict):
+            issuer_arn = issuer.get("arn")
+            if isinstance(issuer_arn, str) and "AWSServiceRoleFor" in issuer_arn:
+                return "service"
+
+    return "interactive"
+
+
+def _derive_read_write(event: dict) -> str:
+    """Return "read" or "write" from top-level readOnly, else verb inference.
+
+    readOnly precedence: boolean True / string "true" → "read"; boolean False /
+    string "false" → "write". Absent readOnly falls back to the action verb:
+    eventName starting with a known read prefix → "read", else "write".
+    """
+    read_only = event.get("readOnly")
+    if read_only is True:
+        return "read"
+    if read_only is False:
+        return "write"
+    if isinstance(read_only, str):
+        lowered = read_only.lower()
+        if lowered == "true":
+            return "read"
+        if lowered == "false":
+            return "write"
+
+    # readOnly absent or in an unrecognised shape — verb inference fallback.
+    name = event.get("eventName")
+    if isinstance(name, str) and name:
+        for prefix in _READ_VERB_PREFIXES:
+            if name.startswith(prefix):
+                return "read"
+    return "write"
+
+
+SNIFF_PEEK_LINES: int = 200
+
+# Quoted-key + colon — matches a JSON key declaration, not a value substring.
+_CT_KEY_RE: dict[str, re.Pattern[str]] = {
+    "Records":      re.compile(r'"Records"\s*:'),
+    "eventVersion": re.compile(r'"eventVersion"\s*:'),
+    "eventTime":    re.compile(r'"eventTime"\s*:'),
+    "userIdentity": re.compile(r'"userIdentity"\s*:'),
+}
+
+_CT_EVENT_KEYS: tuple[str, ...] = ("eventVersion", "eventTime", "userIdentity")
+
+
+def sniff(sample: list[str]) -> str | None:
+    """Recognize CloudTrail JSON (NDJSON event or envelope) and return "cloudtrail".
+
+    Two paths, either one wins:
+
+    1. NDJSON: the first non-empty line parses as a dict containing at least
+       two of ``eventVersion``, ``eventTime``, ``userIdentity``.
+    2. Envelope (structural — does not require the sample to contain a
+       parseable JSON document): the joined sample contains the quoted key
+       ``"Records":`` AND at least two of the three per-event keys
+       (``"eventVersion":``, ``"eventTime":``, ``"userIdentity":``) as
+       quoted-key tokens. Survives pretty-printed envelopes whose first
+       record exceeds the sample budget.
+
+    Returns None when neither path matches.
+
+    Pure: takes already-decoded lines, performs no I/O.
+    """
+    for raw_line in sample:
+        line = raw_line.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except (json.JSONDecodeError, ValueError):
+            break
+        if isinstance(obj, dict):
+            hit = sum(1 for k in _CT_EVENT_KEYS if k in obj)
+            if hit >= 2:
+                return "cloudtrail"
+        break
+
+    joined = "\n".join(sample)
+    if _CT_KEY_RE["Records"].search(joined):
+        hit = sum(1 for k in _CT_EVENT_KEYS if _CT_KEY_RE[k].search(joined))
+        if hit >= 2:
+            return "cloudtrail"
+    return None

loghunter/parsers/dnsmasq.py

@@ -0,0 +1,331 @@
+"""dnsmasq/Pi-hole log parsing — extract structured event dicts for loader assembly.
+
+Provides pure parsing functions with no file I/O.  File discovery, DataFrame
+construction, and hostname assignment are handled by loader.py via load_pihole().
+
+Known limitation: dnsmasq logs carry no timezone information.  Timestamps are
+parsed as if UTC (tzinfo=timezone.utc applied directly to the wall-clock value),
+matching the behaviour of parsers/syslog.py.  When a Pi-hole host runs in a
+non-UTC timezone the ts values will be offset from true UTC by the host's local
+offset; LogHunter's internal timeframe arithmetic is consistent because the same
+convention is applied throughout.
+
+Canonical-plus-event schema
+────────────────────────────
+The parser emits one dict per parsed event line.  Fields divide into two groups:
+
+Canonical DNS fields (shared vocabulary with the Zeek path):
+  ts     — UTC-aware datetime or None
+  src    — querying client IP (str | None; populated ONLY on query events)
+  query  — queried domain (str | None; the "domain" of the event where applicable)
+
+dnsmasq event fields (parser-specific):
+  event_type — query | forwarded | reply | cached | gravity_blocked |
+               config | validation | dnssec_query | special | dhcp |
+               pihole_hostname | regex_blocked | unknown
+  qtype      — query type (A, AAAA, HTTPS, …) (str | None; query and dnssec_query events)
+  dst        — upstream resolver or validation target (str | None; forwarded and
+               dnssec_query events; also holds an opaque token on dhcp rows —
+               not canonical DNS on dhcp; guard with event_type check before use)
+  answer     — answer payload (str | None; reply/cached/gravity_blocked/config/special/
+               pihole_hostname events; also holds an opaque token on dhcp rows —
+               same caveat as dst)
+  validation — DNSSEC status or block disposition phrase (str | None; validation events
+               carry the DNSSEC verdict; regex_blocked events carry the matched
+               disposition phrase e.g. "regex denied", "exactly blacklisted")
+  host       — source host, set by the loader from filename (parser leaves "")
+  raw        — original line
+  message    — message portion after the dnsmasq[PID]: prefix
+
+Rule for detector authors: features may depend on the canonical fields (ts, src,
+query) freely.  Any feature derived from the dnsmasq event fields must be guarded
+(presence-checked) so the same detector code can run against a Zeek frame that
+lacks them.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime
+
+from loghunter.parsers.syslog import parse_timestamp
+
+# ── Compiled patterns ─────────────────────────────────────────────────────────
+
+# Outer grammar: Mon DD HH:MM:SS [hostname] dnsmasq[PID]: <message>
+# Single-digit days appear with a leading space (dnsmasq format); \s+ handles both.
+_OUTER_RE = re.compile(
+    r'^\w{3}\s+\d{1,2}\s+\d{2}:\d{2}:\d{2}'
+    r'\s+(?:\S+\s+)?dnsmasq\[\d+\]:\s+'
+    r'(?P<message>.+)$'
+)
+
+# Inner message grammars — evaluated in order, first match wins.
+_QUERY_RE   = re.compile(
+    r'^query\[(?P<qtype>[^\]]+)\]\s+(?P<domain>\S+)\s+from\s+(?P<src>\S+)'
+)
+_FWD_RE     = re.compile(
+    r'^forwarded\s+(?P<domain>\S+)\s+to\s+(?P<dst>\S+)'
+)
+_REPLY_RE   = re.compile(
+    r'^reply\s+(?P<domain>\S+)\s+is\s+(?P<answer>.+)$'
+)
+_CACHED_RE  = re.compile(
+    r'^(?:cached(?:-stale)?)\s+(?P<domain>\S+)\s+is\s+(?P<answer>.+)$'
+)
+_GRAVITY_RE = re.compile(
+    r'^gravity blocked (?:\([^\)]+\)\s+)?(?P<domain>\S+) is (?P<answer>.+)$'
+)
+_CONFIG_RE  = re.compile(
+    r'^(?P<source>/\S+|config)\s+(?P<domain>\S+)\s+is\s+(?P<answer>.+)$'
+)
+_VALID_RE   = re.compile(
+    r'^validation result is (?P<status>\S+)'
+)
+# dnssec-query: resolver-internal DNSSEC validation traffic. Must precede _FWD_RE
+# as future-proofing — today _FWD_RE starts with "forwarded" so there is no live
+# conflict, but both patterns contain " to " and this ordering makes the intent explicit.
+_DNSSEC_QUERY_RE = re.compile(
+    r'^dnssec-query\[(?P<qtype>[^\]]+)\]\s+(?P<domain>\S+)\s+to\s+(?P<dst>\S+)'
+)
+# special domain: Apple Private Relay / resolver override disposition. Must precede
+# _CONFIG_RE as future-proofing — today _CONFIG_RE starts with "/" or "config" so
+# there is no live conflict, but both match "<token> <domain> is <answer>".
+_SPECIAL_RE = re.compile(
+    r'^special domain\s+(?P<domain>\S+)\s+is\s+(?P<answer>.+)$'
+)
+# Pi-hole hostname self-resolution. Must precede _CONFIG_RE for the same reason as
+# _SPECIAL_RE — the "Pi-hole hostname" literal prefix is unambiguous today but the
+# ordering makes the intent explicit.
+_PIHOLE_HOSTNAME_RE = re.compile(
+    r'^Pi-hole hostname\s+(?P<domain>\S+)\s+is\s+(?P<answer>.+)$'
+)
+# Regex/blacklist block disposition. Covers the spelling variants FTL emits across
+# versions: "regex denied", "regex blacklisted", "exactly denied", "exactly blacklisted",
+# and bare "blacklisted". Must precede _CONFIG_RE — the "<token(s)> <domain> is <answer>"
+# shape overlaps, and the literal disposition prefix is unambiguous.
+_REGEX_BLOCKED_RE = re.compile(
+    r'^(?P<disposition>regex (?:denied|blacklisted)|exactly (?:denied|blacklisted)|blacklisted)'
+    r'\s+(?P<domain>\S+)\s+is\s+(?P<answer>.+)$'
+)
+# DHCP lease lines ride the same log file. Both field orders occur in the wild:
+# "DHCP <ip> is <hostname>" AND "DHCP <hostname> is <ip>".
+_DHCP_RE    = re.compile(
+    r'^DHCP\s+(?P<a>\S+)\s+is\s+(?P<b>\S+)'
+)
+
+
+# ── Parsing functions ─────────────────────────────────────────────────────────
+
+def parse_line(raw: str) -> dict | None:
+    """Parse a raw dnsmasq log line into a normalized event dict.
+
+    Returns None for blank lines, comment lines (starting with #), and lines
+    that do not match the dnsmasq outer grammar.
+
+    Returns a dict with the canonical-plus-event schema described in the module
+    docstring.  All keys are always present.  The 'host' field is left as "" —
+    the loader fills it from the filename stem before building the DataFrame.
+    The 'event_type' is "unknown" when the outer grammar matches but no inner
+    grammar does; 'query' is None in that case.  Unknown lines are retained
+    (not dropped) so the detector session can discover new message patterns.
+    """
+    if not raw or raw.lstrip().startswith("#"):
+        return None
+
+    m = _OUTER_RE.match(raw.strip())
+    if not m:
+        return None
+
+    message = m.group("message")
+    ts: datetime | None = parse_timestamp(raw)
+
+    result: dict = {
+        "ts":         ts,
+        "src":        None,
+        "query":      None,
+        "event_type": "unknown",
+        "qtype":      None,
+        "dst":        None,
+        "answer":     None,
+        "validation": None,
+        "host":       "",
+        "raw":        raw,
+        "message":    message,
+    }
+
+    m_q = _QUERY_RE.match(message)
+    if m_q:
+        result.update({
+            "event_type": "query",
+            "qtype":      m_q.group("qtype"),
+            "query":      m_q.group("domain"),
+            "src":        m_q.group("src"),
+        })
+        return result
+
+    # dhcp rows are non-DNS DHCP lease events that ride the dnsmasq log file.
+    # They are excluded from all DNS analysis. Parsed here only to keep the unknown
+    # bucket clean and to let the detector trivially filter with event_type == "dhcp".
+    # dst and answer hold the two raw "DHCP <a> is <b>" tokens as opaque strings;
+    # the "is" separator does NOT mean domain/answer here. Do not use dst or answer
+    # from dhcp rows in any DNS aggregation — guard with event_type == "dhcp" first.
+    m_dhcp = _DHCP_RE.match(message)
+    if m_dhcp:
+        result.update({
+            "event_type": "dhcp",
+            "dst":    m_dhcp.group("a"),   # opaque — not a DNS resolver address
+            "answer": m_dhcp.group("b"),   # opaque — not a DNS answer
+        })
+        return result
+
+    # dnssec-query events are resolver-internal DNSSEC validation traffic keyed to
+    # zone-cut labels and root-style validation targets (e.g. example.test, or the
+    # root zone) that frequently NEVER appear as a client query. They must NOT be
+    # counted as "forwarded" events and must NOT be merged into per-domain query
+    # aggregation by default — doing so would inflate forward_ratio for domains with
+    # zero client queries and reproduce the divide-by-zero/infinite-ratio problem
+    # observed during exploration. Capture now; defer feature use to a deliberate
+    # later decision.
+    m_dq = _DNSSEC_QUERY_RE.match(message)
+    if m_dq:
+        result.update({
+            "event_type": "dnssec_query",
+            "qtype":      m_dq.group("qtype"),
+            "query":      m_dq.group("domain"),
+            "dst":        m_dq.group("dst"),
+        })
+        return result
+
+    m_f = _FWD_RE.match(message)
+    if m_f:
+        result.update({
+            "event_type": "forwarded",
+            "query":      m_f.group("domain"),
+            "dst":        m_f.group("dst"),
+        })
+        return result
+
+    m_r = _REPLY_RE.match(message)
+    if m_r:
+        result.update({
+            "event_type": "reply",
+            "query":      m_r.group("domain"),
+            "answer":     m_r.group("answer").strip(),
+        })
+        return result
+
+    m_c = _CACHED_RE.match(message)
+    if m_c:
+        result.update({
+            "event_type": "cached",
+            "query":      m_c.group("domain"),
+            "answer":     m_c.group("answer").strip(),
+        })
+        return result
+
+    m_g = _GRAVITY_RE.match(message)
+    if m_g:
+        result.update({
+            "event_type": "gravity_blocked",
+            "query":      m_g.group("domain"),
+            "answer":     m_g.group("answer").strip(),
+        })
+        return result
+
+    m_sp = _SPECIAL_RE.match(message)
+    if m_sp:
+        result.update({
+            "event_type": "special",
+            "query":      m_sp.group("domain"),
+            "answer":     m_sp.group("answer").strip(),
+        })
+        return result
+
+    # pihole_hostname rows are Pi-hole's own host self-resolution chatter (FTL
+    # answering for its own hostname). They have no DNS hunting value and are
+    # excluded from all DNS aggregation. Parsed here only to keep the unknown
+    # bucket clean; the detector filters them out with event_type == "pihole_hostname".
+    m_ph = _PIHOLE_HOSTNAME_RE.match(message)
+    if m_ph:
+        result.update({
+            "event_type": "pihole_hostname",
+            "query":      m_ph.group("domain"),
+            "answer":     m_ph.group("answer").strip(),
+        })
+        return result
+
+    # regex_blocked and gravity_blocked are TWO mechanisms of the SAME outcome
+    # (Pi-hole refused to resolve). The parser keeps them DISTINCT because the
+    # gravity-vs-regex distinction is a real Pi-hole config detail worth preserving
+    # at the source. The DETECTOR is responsible for collapsing both into a single
+    # "blocked" notion when computing block_ratio / was_blocked — do not collapse
+    # them here. (Separation of powers: parser stays faithful to the source; detector
+    # owns the abstraction.)
+    # The disposition phrase is stored in the validation field — the same field used
+    # for DNSSEC verdicts — because both describe the resolution outcome and no new
+    # schema column is needed. Guard with event_type == "regex_blocked" before using.
+    m_rb = _REGEX_BLOCKED_RE.match(message)
+    if m_rb:
+        result.update({
+            "event_type": "regex_blocked",
+            "query":      m_rb.group("domain"),
+            "answer":     m_rb.group("answer").strip(),
+            "validation": m_rb.group("disposition"),
+        })
+        return result
+
+    m_cf = _CONFIG_RE.match(message)
+    if m_cf:
+        result.update({
+            "event_type": "config",
+            "query":      m_cf.group("domain"),
+            "answer":     m_cf.group("answer").strip(),
+        })
+        return result
+
+    m_v = _VALID_RE.match(message)
+    if m_v:
+        result.update({
+            "event_type": "validation",
+            "validation": m_v.group("status"),
+        })
+        return result
+
+    # No inner grammar matched — return as unknown; query stays None.
+    return result
+
+
+SNIFF_PEEK_LINES: int = 32
+
+# Event types that prove the file is a dnsmasq/Pi-hole DNS log. dhcp and
+# unknown are intentionally absent — they may precede the first DNS event
+# but never claim "dns" on their own.
+_DNS_BEARING_EVENT_TYPES: frozenset[str] = frozenset({
+    "query", "forwarded", "reply", "cached",
+    "gravity_blocked", "regex_blocked",
+    "config", "validation",
+    "dnssec_query", "special", "pihole_hostname",
+})
+
+
+def sniff(sample: list[str]) -> str | None:
+    """Recognize a dnsmasq/Pi-hole DNS log and return "dns".
+
+    Calls ``parse_line`` on each sample line and inspects ``event_type``.
+    Returns "dns" on the first line whose event_type is a DNS-bearing kind
+    (query/forwarded/reply/cached/gravity_blocked/regex_blocked/config/
+    validation/dnssec_query/special/pihole_hostname). Tolerates leading
+    runs of DHCP-lease or unknown dnsmasq chatter — they do not short-
+    circuit. Returns None when the budget is exhausted without a
+    DNS-bearing event, or when no line matches the dnsmasq outer grammar.
+
+    Pure: takes already-decoded lines, performs no I/O.
+    """
+    for raw_line in sample:
+        record = parse_line(raw_line)
+        if record is None:
+            continue
+        if record["event_type"] in _DNS_BEARING_EVENT_TYPES:
+            return "dns"
+    return None