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

loghunter/cli.py

@@ -0,0 +1,1108 @@
+"""CLI dispatcher — argument parsing, subcommand routing, and first-run experience.
+
+Entry point: loghunter.cli:main (registered in pyproject.toml).
+
+Dispatch table:
+  loghunter [options] PATH           run all enabled detectors via runner
+  loghunter beacon|dns|syslog|...   run a single detector
+  loghunter digest [PATH ...]       orient-before-the-hunt card (sniff-driven)
+  loghunter export                   pull logs from external systems
+  loghunter init                     first-run setup wizard
+
+Parsing is a small declarative spec (``_FLAG_LIST`` + ``_VERBS``) plus a
+per-token loop (``_parse_args``). The spec governs allowed-flag membership,
+validation, and generated per-command help. ``blob_path`` is NOT a flag —
+it is an INTERNAL routing key synthesized post-sniff and MUST NOT enter
+the spec.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any
+
+from loghunter.common import config as cfg
+from loghunter.common.errors import DigestEmpty, ExportAborted
+from loghunter.common.output import get_handler
+from loghunter.common.paths import be_like_water, effective_root, resolve_path
+
+
+# ── flag/verb spec ────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class FlagSpec:
+    """One advertised CLI flag.
+
+    ``key`` is the underscore canonical key used by ``parsed[...]``, config,
+    and runner kwargs — never the hyphenated display spelling.
+    """
+    key: str
+    long: str
+    short: str | None
+    takes_value: bool
+    metavar: str
+    help: str
+
+
+# Ordered list — also the display order for generated per-command help.
+_FLAG_LIST: tuple[FlagSpec, ...] = (
+    FlagSpec("help",             "--help",             "h",  False, "",
+             "show this help and exit"),
+    FlagSpec("verbose",          "--verbose",          "v",  False, "",
+             "verbose output (extended evidence and next-steps; -vv for full raw debug detail)"),
+    FlagSpec("yes",              "--yes",              "y",  False, "",
+             "assume yes to advisory prompts (large-dataset, egress)"),
+    FlagSpec("all",              "--all",              "a",  False, "",
+             "load all available data; overrides default window"),
+    FlagSpec("out",              "--out",              "o",  True,  "PATH",
+             "single per-run output target (file or dir; trailing / = dir)"),
+    FlagSpec("config",           "--config",           "c",  True,  "FILE",
+             "path to a config file (overrides search-path lookup)"),
+    FlagSpec("since",            "--since",            "s",  True,  "DURATION|DATE",
+             "window start (7d, 24h, or ISO date)"),
+    FlagSpec("detect",           "--detect",           "d",  True,  "LIST",
+             "detector selection (all, comma list, or 'all,!x,!y')"),
+    FlagSpec("dry_run",          "--dry-run",          None, False, "",
+             "show the plan without running detectors / writing output"),
+    FlagSpec("export_allowlist", "--export-allowlist", None, False, "",
+             "emit allowlist-ready lines instead of a report (stubbed)"),
+    FlagSpec("output",           "--output",           None, True,  "FORMAT",
+             "output format (text, json, csv, html)"),
+    FlagSpec("until",            "--until",            None, True,  "DATE",
+             "window end (ISO date)"),
+    FlagSpec("days",             "--days",             None, True,  "N-M",
+             "days-ago range (e.g. 1-7); order-insensitive"),
+    FlagSpec("hours",            "--hours",            None, True,  "N-M",
+             "hours-ago range (e.g. 0-2); order-insensitive"),
+    FlagSpec("zeek_dir",         "--zeek-dir",         None, True,  "PATH",
+             "Zeek log directory (overrides config)"),
+    FlagSpec("pihole_dir",       "--pihole-dir",       None, True,  "PATH",
+             "Pi-hole / dnsmasq log directory (overrides config)"),
+    FlagSpec("syslog_dir",       "--syslog-dir",       None, True,  "PATH",
+             "rsyslog log directory (overrides config)"),
+    FlagSpec("cloudtrail_dir",   "--cloudtrail-dir",   None, True,  "PATH",
+             "CloudTrail JSON directory (overrides config)"),
+)
+
+_FLAGS_BY_KEY: dict[str, FlagSpec] = {f.key: f for f in _FLAG_LIST}
+_FLAGS_BY_LONG: dict[str, FlagSpec] = {f.long: f for f in _FLAG_LIST}
+_FLAGS_BY_SHORT: dict[str, FlagSpec] = {f.short: f for f in _FLAG_LIST if f.short}
+
+
+@dataclass(frozen=True)
+class VerbSpec:
+    """One verb in the dispatcher.
+
+    ``name == ""`` represents the analyze/no-verb path. ``allowed`` is the set
+    of canonical flag keys (not long spellings) — short flags are aliases for
+    their canonical key, so a short flag is allowed iff its canonical key is
+    in ``allowed``.
+    """
+    name: str
+    summary: str
+    positional_shape: str
+    allowed: frozenset[str]
+
+
+_ANALYZE_ALLOWED: frozenset[str] = frozenset({
+    "help", "verbose", "yes", "all", "out", "config", "since", "detect",
+    "dry_run", "export_allowlist", "output", "until", "days", "hours",
+    "zeek_dir", "pihole_dir", "syslog_dir", "cloudtrail_dir",
+})
+_SINGLE_DET_ALLOWED: frozenset[str] = _ANALYZE_ALLOWED - {"detect"}
+_DIGEST_ALLOWED: frozenset[str] = frozenset({
+    "help", "verbose", "yes", "all", "out", "config", "since",
+    "dry_run", "output", "until", "days", "hours", "zeek_dir",
+})
+_EXPORT_ALLOWED: frozenset[str] = frozenset({
+    "help", "verbose", "yes", "out", "config", "since", "until", "days", "hours",
+})
+_INIT_ALLOWED: frozenset[str] = frozenset({"help"})
+
+
+_VERBS: dict[str, VerbSpec] = {
+    "":         VerbSpec("",         "run all enabled detectors",
+                         "[PATH]", _ANALYZE_ALLOWED),
+    "beacon":   VerbSpec("beacon",   "beacon detection (conn.log)",
+                         "[PATH]", _SINGLE_DET_ALLOWED),
+    "dns":      VerbSpec("dns",      "DNS clustering (Zeek or Pi-hole)",
+                         "[PATH]", _SINGLE_DET_ALLOWED),
+    "syslog":   VerbSpec("syslog",   "syslog anomaly detection",
+                         "[PATH]", _SINGLE_DET_ALLOWED),
+    "scan":     VerbSpec("scan",     "port scan detection (conn.log)",
+                         "[PATH]", _SINGLE_DET_ALLOWED),
+    "duration": VerbSpec("duration", "long connection detection (conn.log)",
+                         "[PATH]", _SINGLE_DET_ALLOWED),
+    "aws":      VerbSpec("aws",      "CloudTrail behavioral surfacing (per-principal)",
+                         "[PATH]", _SINGLE_DET_ALLOWED),
+    "digest":   VerbSpec("digest",   "orient-before-the-hunt card (schema sniffed)",
+                         "[PATH ...]", _DIGEST_ALLOWED),
+    "export":   VerbSpec("export",   "pull logs from external systems to local files",
+                         "[BACKEND] [QUERY ...]", _EXPORT_ALLOWED),
+    "init":     VerbSpec("init",     "first-run setup wizard",
+                         "", _INIT_ALLOWED),
+}
+
+
+_SINGLE_DETECTOR_COMMANDS: frozenset[str] = frozenset({
+    "beacon", "dns", "syslog", "scan", "duration", "aws",
+})
+
+# User-initiated stop (Ctrl-C during compute). Named so the future error-voice
+# pass can find the message and exit code together. 130 is the Unix 128 + SIGINT
+# convention. Ctrl-C AT THE CONFIRM PROMPTS (runner.py) is a separate path that
+# routes through ExportAborted → exit 0; this is the mid-run sibling.
+_STOPPED_MESSAGE = "Stopped."
+_SIGINT_EXIT_CODE = 130
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Parse arguments and dispatch to the appropriate subcommand or runner."""
+    try:
+        rc = _main(argv) or 0
+    except KeyboardInterrupt:
+        # Most terminals echo Ctrl-C as "^C" with no trailing newline before
+        # Python sees the signal. Without a leading blank line on TTY stderr,
+        # our message lands as "^CStopped." on one row. Non-TTY stderr stays
+        # byte-exact at "Stopped.\n" so log capture / scripts are unaffected.
+        if sys.stderr.isatty():
+            print(file=sys.stderr)
+        print(_STOPPED_MESSAGE, file=sys.stderr)
+        sys.exit(_SIGINT_EXIT_CODE)
+    except ExportAborted as exc:
+        print(str(exc))
+        sys.exit(0)
+    except cfg.ConfigError as exc:
+        print(f"loghunter: {exc}", file=sys.stderr)
+        sys.exit(1)
+    except ValueError as exc:
+        print(f"loghunter: {exc}", file=sys.stderr)
+        print("Run 'loghunter --help' for usage.", file=sys.stderr)
+        sys.exit(1)
+    except OSError as exc:
+        print(f"loghunter: {exc}", file=sys.stderr)
+        sys.exit(1)
+    if rc:
+        sys.exit(rc)
+
+
+def _main(argv: list[str] | None = None) -> int:
+    """Internal CLI dispatcher. Exceptions are formatted by main().
+
+    Returns an int exit code; only the digest fan-out currently uses non-zero
+    (its three-way exit policy). Every other branch returns 0.
+    """
+    args = argv if argv is not None else sys.argv[1:]
+
+    if not args or args == ["--help"] or args == ["-h"]:
+        _print_global_usage()
+        return 0
+
+    cand = args[0]
+
+    if cand in _SINGLE_DETECTOR_COMMANDS:
+        verb = cand
+        rest = args[1:]
+    elif cand == "digest":
+        verb = "digest"
+        rest = args[1:]
+    elif cand == "init":
+        verb = "init"
+        rest = args[1:]
+    elif cand == "export":
+        verb = "export"
+        rest = args[1:]
+    elif cand.startswith("-") or _looks_like_path(cand):
+        verb = ""
+        rest = args
+    else:
+        print(f"loghunter: unknown command '{cand}'", file=sys.stderr)
+        print("Run 'loghunter --help' for usage.", file=sys.stderr)
+        sys.exit(1)
+
+    # Side-effect-light help short-circuit — STANDALONE --help / -h ONLY.
+    # `--help=anything` and `-h=anything` are NOT help; they fall through to
+    # the strict parser and produce "takes no value". This fires BEFORE
+    # config load, output resolution, sniff dispatch, or wizard entry.
+    if any(tok == "--help" or tok == "-h" for tok in rest):
+        print(_render_verb_help(verb), end="")
+        return 0
+
+    if verb in _SINGLE_DETECTOR_COMMANDS:
+        _run_single_detector(verb, rest)
+    elif verb == "digest":
+        return _run_digest(rest) or 0
+    elif verb == "init":
+        _run_init(rest)
+    elif verb == "export":
+        _run_export(rest)
+    else:
+        _run_all_detectors(rest)
+    return 0
+
+
+def _looks_like_path(s: str) -> bool:
+    """Return True if the string looks like a filesystem path rather than a subcommand.
+
+    Verbs are matched first in ``_main`` so verb names always win; this only
+    decides whether a non-verb token routes to the analyze path or fails as
+    an unknown command. The ``os.path.exists`` clause catches bare filenames
+    in CWD (``loghunter conn.log``) that the prefix tests would miss.
+    """
+    if s.startswith("/") or s.startswith("~") or s.startswith("."):
+        return True
+    if "/" in s:
+        return True
+    try:
+        if os.path.exists(s):
+            return True
+    except (OSError, ValueError):
+        pass
+    return False
+
+
+# ── usage / help generation ───────────────────────────────────────────────────
+
+
+def _global_usage_text() -> str:
+    """Compose the bare-loghunter / --help screen from the spec."""
+    lines = [
+        "loghunter — network threat hunting for self-hosters",
+        "",
+        "Usage:",
+        "  loghunter [options] PATH           run all enabled detectors",
+        "  loghunter beacon [options] PATH    beacon detection (conn.log)",
+        "  loghunter dns [options] PATH       DNS clustering (Zeek or Pi-hole)",
+        "  loghunter syslog [options] PATH    syslog anomaly detection",
+        "  loghunter scan [options] PATH      port scan detection (conn.log)",
+        "  loghunter duration [options] PATH  long connection detection (conn.log)",
+        "  loghunter aws [options] PATH       CloudTrail behavioral surfacing (per-principal)",
+        "",
+        "  loghunter digest [options] PATH    orient-before-the-hunt card; schema is",
+        "                                     inferred from the file (conn, dns, syslog,",
+        "                                     cloudtrail, or blob for unrecognized text)",
+        "",
+        "  loghunter export                   pull logs from external systems",
+        "  loghunter init                     first-run setup wizard",
+        "",
+        "Common options (short forms shown for the frequently-typed flags):",
+        "  --help, -h         --verbose, -v      --yes, -y          --all, -a",
+        "  --out, -o=PATH     --config, -c=FILE  --since, -s=…      --detect, -d=LIST",
+        "",
+        "Less common: --dry-run --export-allowlist --output=FORMAT --until=DATE",
+        "             --days=N-M --hours=N-M",
+        "             --zeek-dir=PATH --syslog-dir=PATH --pihole-dir=PATH --cloudtrail-dir=PATH",
+        "",
+        "Run 'loghunter <command> --help' for command-specific options.",
+        "",
+    ]
+    return "\n".join(lines)
+
+
+def _print_global_usage() -> None:
+    """Print the first-run usage message, appending a hint when no config is found."""
+    print(_global_usage_text(), end="")
+    if cfg._find_config_file() is None:
+        print("  No config found. Run 'loghunter init' to get started.")
+        print("  Config will be written to ~/.loghunter/config.toml")
+
+
+# Compatibility alias — internal helper kept under its historical name for
+# tests/observers that import it directly.
+_print_usage = _print_global_usage
+
+
+def _render_verb_help(verb: str) -> str:
+    """Render per-command help from the spec — drives `<verb> --help` / `-h`."""
+    vs = _VERBS[verb]
+    cmd = "loghunter" + (f" {verb}" if verb else "")
+    shape = f" {vs.positional_shape}" if vs.positional_shape else ""
+    lines = [f"Usage: {cmd} [options]{shape}".rstrip(), "", vs.summary, "", "Options:"]
+    # Preserve display order from _FLAG_LIST so output is stable.
+    for spec in _FLAG_LIST:
+        if spec.key not in vs.allowed:
+            continue
+        if spec.short:
+            head = f"  {spec.long}, -{spec.short}"
+        else:
+            head = f"  {spec.long}"
+        if spec.takes_value:
+            head += f"={spec.metavar}"
+        lines.append(f"{head:<32} {spec.help}".rstrip())
+    return "\n".join(lines) + "\n"
+
+
+# ── parser ────────────────────────────────────────────────────────────────────
+
+
+def _parse_args(args: list[str], verb: str) -> dict[str, Any]:
+    """Parse CLI tokens for ``verb`` into a kwargs dict.
+
+    Validation order is BINDING: identity → verb-membership → value-shape. A
+    globally-known but verb-disallowed flag yields the wrong-verb error
+    regardless of value shape (``digest -d`` and ``digest --detect`` both
+    report "not valid for digest", NOT "needs a value").
+
+    Duplicate flags are last-wins (preserving the original dict-overwrite
+    behavior). Single-valued — never promoted to a list.
+
+    Positionals: ``parsed["path"]`` = first; ``parsed["paths"]`` = full list.
+    """
+    if verb not in _VERBS:
+        raise ValueError(f"unknown verb {verb!r}")
+    allowed = _VERBS[verb].allowed
+    verb_label = verb if verb else "analyze"
+
+    def _wrong_verb_long(spec: FlagSpec) -> str:
+        alias = f" (-{spec.short})" if spec.short else ""
+        return f"{spec.long}{alias} is not valid for {verb_label}"
+
+    def _wrong_verb_short(spec: FlagSpec) -> str:
+        # Short was typed; lead with the short, alias is the long.
+        return f"-{spec.short} ({spec.long}) is not valid for {verb_label}"
+
+    def _needs_value(spec: FlagSpec) -> str:
+        alias = f" (-{spec.short})" if spec.short else ""
+        short_hint = f"-{spec.short}=… or " if spec.short else ""
+        return f"{spec.long}{alias} needs a value: {short_hint}{spec.long}=…"
+
+    def _no_value(spec: FlagSpec) -> str:
+        alias = f" (-{spec.short})" if spec.short else ""
+        return f"{spec.long}{alias} takes no value"
+
+    result: dict[str, Any] = {}
+    positionals: list[str] = []
+
+    for arg in args:
+        # `-vv` is a SINGLE explicitly-registered literal token — the one-off
+        # spelling for verbose-level 2. Recognized BEFORE the normal short-flag
+        # branch so the bundling-refusal lattice ("can't be combined") never
+        # catches it. Anything longer (-vvv, -vy) falls through to the bundling
+        # path and gets the existing pass-separately message. Wrong-verb parity:
+        # `loghunter init -vv` raises the same wrong-verb error as
+        # `loghunter init -v`, never "unknown flag" / "needs a value".
+        if arg == "-vv":
+            v_spec = _FLAGS_BY_SHORT.get("v")
+            if v_spec is None or v_spec.key not in allowed:
+                raise ValueError(_wrong_verb_short(v_spec))
+            result["verbose_level"] = 2
+            continue
+        if arg.startswith("--"):
+            body, eq, val = arg[2:].partition("=")
+            long_form = f"--{body}"
+            spec = _FLAGS_BY_LONG.get(long_form)
+            if spec is None:
+                raise ValueError(f"unknown flag --{body}")
+            if spec.key not in allowed:
+                raise ValueError(_wrong_verb_long(spec))
+            if eq:
+                if not spec.takes_value:
+                    raise ValueError(_no_value(spec))
+                result[spec.key] = val
+            else:
+                if spec.takes_value:
+                    raise ValueError(_needs_value(spec))
+                result[spec.key] = True
+        elif arg.startswith("-") and arg != "-":
+            stripped = arg[1:]
+            body, eq, val = stripped.partition("=")
+            if len(body) == 1:
+                short = body
+                spec = _FLAGS_BY_SHORT.get(short)
+                if spec is None:
+                    raise ValueError(f"unknown flag -{short}")
+                if spec.key not in allowed:
+                    raise ValueError(_wrong_verb_short(spec))
+                if eq:
+                    if not spec.takes_value:
+                        raise ValueError(_no_value(spec))
+                    result[spec.key] = val
+                else:
+                    if spec.takes_value:
+                        raise ValueError(_needs_value(spec))
+                    result[spec.key] = True
+            elif len(body) > 1:
+                # Bundling attempt — deliberately declined. Surface kindly when
+                # every char is a known short; otherwise plain unknown-flag.
+                if all(ch in _FLAGS_BY_SHORT for ch in body):
+                    separated = " ".join(f"-{ch}" for ch in body)
+                    raise ValueError(
+                        f"short flags can't be combined (-{body}); "
+                        f"pass separately: {separated}"
+                    )
+                raise ValueError(f"unknown flag -{body}")
+            else:
+                raise ValueError(f"unknown flag {arg}")
+        else:
+            positionals.append(arg)
+
+    if positionals:
+        result["path"] = positionals[0]
+        result["paths"] = positionals
+
+    return result
+
+
+# ── shared resolution helpers ─────────────────────────────────────────────────
+
+
+def _assert_all_vs_timeframe(parsed: dict[str, Any]) -> None:
+    """``--all`` is mutually exclusive with explicit timeframe flags."""
+    if parsed.get("all") and any(k in parsed for k in ("since", "until", "days", "hours")):
+        raise ValueError(
+            "--all cannot be combined with --since, --until, --days, or --hours"
+        )
+
+
+def _resolve_output_target(
+    parsed: dict[str, Any], config: dict[str, Any],
+) -> tuple[Path | None, Path | None]:
+    """Resolve the ``--out`` / ``[loghunter].report_dir`` ladder.
+
+    Returns ``(output_file, output_dir)`` — exactly one of which is non-None
+    when a target is set; both ``None`` means stdout.
+    """
+    cfg_lh = config.get("loghunter", {})
+    root = effective_root(config)
+    cli_out = parsed.get("out") if "out" in parsed else None
+    if cli_out:
+        target = resolve_path(cli_out, "")
+    else:
+        target = resolve_path(cfg_lh.get("report_dir"), root)
+
+    if target is None:
+        return None, None
+    resolved = be_like_water(target)
+    if resolved.is_file:
+        return resolved.path, None
+    return None, resolved.path
+
+
+def _resolve_timeframe(
+    parsed: dict[str, Any],
+    now: datetime | None = None,
+) -> tuple[datetime | None, datetime | None]:
+    """Convert --since/--until/--days/--hours into a (since, until) datetime pair."""
+    if now is None:
+        now = datetime.now(timezone.utc)
+    since: datetime | None = None
+    until: datetime | None = None
+
+    if "days" in parsed:
+        a, b = _parse_range(str(parsed["days"]), "--days")
+        since = (now - timedelta(days=b)).replace(hour=0, minute=0, second=0, microsecond=0)
+        until = (now - timedelta(days=a)).replace(hour=23, minute=59, second=59, microsecond=0)
+        return since, until
+
+    if "hours" in parsed:
+        a, b = _parse_range(str(parsed["hours"]), "--hours")
+        since = now - timedelta(hours=b)
+        until = now - timedelta(hours=a)
+        return since, until
+
+    if "since" in parsed:
+        s = str(parsed["since"])
+        if s.endswith("d"):
+            since = now - timedelta(days=_parse_positive_int(s[:-1], "--since"))
+        elif s.endswith("h"):
+            since = now - timedelta(hours=_parse_positive_int(s[:-1], "--since"))
+        else:
+            since = _parse_iso_date(s, "--since")
+
+    if "until" in parsed:
+        until = _parse_iso_date(str(parsed["until"]), "--until")
+
+    return since, until
+
+
+def _parse_range(value: str, flag: str) -> tuple[int, int]:
+    """Parse N-M range arguments for --days and --hours."""
+    parts = value.split("-")
+    if len(parts) != 2:
+        raise ValueError(f"{flag} expects a range like 3-5")
+    try:
+        start, end = sorted(int(part) for part in parts)
+    except ValueError as exc:
+        raise ValueError(f"{flag} expects numeric values like 3-5") from exc
+    return start, end
+
+
+def _parse_positive_int(value: str, flag: str) -> int:
+    """Parse a positive integer embedded in a duration flag."""
+    try:
+        parsed = int(value)
+    except ValueError as exc:
+        raise ValueError(f"{flag} expects a duration like 7d or 24h") from exc
+    if parsed < 0:
+        raise ValueError(f"{flag} duration must be positive")
+    return parsed
+
+
+def _parse_iso_date(value: str, flag: str) -> datetime:
+    """Parse an ISO date/time as UTC for CLI timeframe flags."""
+    try:
+        parsed = datetime.fromisoformat(value)
+    except ValueError as exc:
+        raise ValueError(f"{flag} expects a date like 2026-05-01") from exc
+    return parsed.replace(tzinfo=timezone.utc)
+
+
+# ── runner-kwargs builders ────────────────────────────────────────────────────
+
+
+def _resolve_verbose_level(parsed: dict[str, Any]) -> int:
+    """Collapse the parser's two-key verbose state into a single 0/1/2 dial.
+
+    ``-vv`` is registered as the literal token ``verbose_level=2`` (see
+    ``_parse_args``); ``-v`` / ``--verbose`` set ``verbose=True``. Their
+    last-wins resolution lands here:
+        none → 0; -v → 1; -vv → 2; combined → 2.
+    Only the text handler distinguishes all three levels; every other
+    consumer collapses to ``>= 1`` (export internals, csv/html description
+    gate, digest summariser-failure breadcrumb).
+    """
+    if parsed.get("verbose_level") == 2:
+        return 2
+    return 1 if parsed.get("verbose") else 0
+
+
+_ANALYZE_SOURCE_KEYS: tuple[str, ...] = (
+    "zeek_dir", "syslog_dir", "pihole_dir", "cloudtrail_dir",
+)
+
+
+def _merge_family_value(
+    bucket: list[str], flag_value: str | None,
+) -> str | list[str] | None:
+    """Combine a positional-derived bucket with the explicit ``--<family>-dir``
+    flag value, returning the runner-kwarg shape for that family.
+
+    MERGE rule (sanctioned rail supersession in the rev-3 prompt — James
+    reconciles CODE.md after landing): positionals routed to the family
+    + the flag value BOTH contribute, both load. Order is positionals
+    first, flag appended; dedup is the loader's job (via ``.resolve()``).
+
+    Wire-shape compression for the runner kwarg:
+
+    - empty + no flag → ``None`` (no override; config fallback within scope)
+    - exactly one truthy value → scalar (string) — keeps programmatic
+      scalar-caller shape byte-identical with the prior single-Path contract
+    - 2+ values → ``list[str]`` — the multi-input shape
+
+    All three shapes flow through ``runner.run`` → ``resolve_sources`` →
+    ``_normalize_overrides``, which collapses to the same downstream
+    ``list[Path]`` regardless. Raw strings only — the CLI does NOT
+    ``Path(...)`` or ``resolve_path`` source values; ``_resolve_one`` is
+    the SOLE string→Path site.
+    """
+    merged: list[str] = [b for b in bucket if b]
+    if flag_value:
+        merged.append(flag_value)
+    if not merged:
+        return None
+    if len(merged) == 1:
+        return merged[0]
+    return merged
+
+
+def _build_positional_buckets(
+    paths: list[str], *, detector_module: Any | None,
+) -> dict[str, list[str]]:
+    """Sniff-classify each positional into its source-family bucket.
+
+    Returns ``{family_key: [positional, …]}`` for the families touched.
+    ``detector_module=None`` triggers the router's content-sniff mode
+    (detect=all / unknown selector). Empty input → empty dict.
+    """
+    from loghunter.common.sources import route_positional_source
+
+    buckets: dict[str, list[str]] = {}
+    for p in paths:
+        routed = route_positional_source(p, detector_module=detector_module)
+        buckets.setdefault(routed, []).append(p)
+    return buckets
+
+
+def _runner_kwargs(
+    parsed: dict[str, Any],
+    config: dict[str, Any],
+    detect: str | None = None,
+    scope: frozenset[str] | None = None,
+    source_buckets: dict[str, list[str]] | None = None,
+) -> dict[str, Any]:
+    """Build the kwargs dict for runner.run() from parsed CLI args and loaded config.
+
+    Source-dir overrides flow through as raw parsed strings, per-family lists,
+    or ``None``. The CLI does NOT call ``resolve_path`` or ``Path(...)`` for
+    source dirs — ``loghunter.common.sources._resolve_one`` is the SOLE site
+    where a source-dir string becomes a resolved ``Path``. The runner threads
+    the raw values into ``resolve_sources``, which normalizes scalar/list/None
+    uniformly.
+
+    ``source_buckets`` carries the per-positional sniff classification
+    (``{family_key: [positional_path, …]}``). For each family the bucket is
+    MERGED with the explicit ``--<family>-dir`` flag (positionals first, flag
+    appended) — the sanctioned rail supersession from the rev-3 prompt:
+    same-family flag + positional now BOTH load instead of "flag wins."
+
+    ``scope`` is the SOLE scoping signal: ``None`` = unconstrained,
+    ``frozenset(touched_families)`` = scope the run so sibling source-dirs
+    stay unloaded. The caller computes ``scope`` from the bucket keys; a
+    positional ALWAYS scopes. An explicit override outside ``scope`` still
+    applies — the operator widening the run deliberately.
+    """
+    _assert_all_vs_timeframe(parsed)
+
+    since, until = _resolve_timeframe(parsed)
+    cfg_lh = config.get("loghunter", {})
+
+    output_file, output_dir = _resolve_output_target(parsed, config)
+
+    buckets = source_buckets or {}
+    family_values: dict[str, str | list[str] | None] = {
+        key: _merge_family_value(buckets.get(key, []), parsed.get(key))
+        for key in _ANALYZE_SOURCE_KEYS
+    }
+
+    return dict(
+        config=config,
+        detect=detect or parsed.get("detect"),
+        # Source-dir overrides: raw strings / lists / None — resolver owns Path conversion.
+        zeek_dir=family_values["zeek_dir"],
+        syslog_dir=family_values["syslog_dir"],
+        pihole_dir=family_values["pihole_dir"],
+        cloudtrail_dir=family_values["cloudtrail_dir"],
+        scope=scope,
+        since=since,
+        until=until,
+        output_format=parsed.get("output", cfg_lh.get("output_format", "text")),
+        output_dir=output_dir,
+        output_file=output_file,
+        verbose_level=_resolve_verbose_level(parsed),
+        dry_run=bool(parsed.get("dry_run", False)),
+        export_allowlist=bool(parsed.get("export_allowlist", False)),
+        load_all=bool(parsed.get("all", False)),
+        skip_confirm=bool(parsed.get("yes", False)),
+    )
+
+
+# ── verb runners ──────────────────────────────────────────────────────────────
+
+
+def _named_detector_module(detect: Any) -> Any:
+    """Return the imported detector module for an exactly-one-detector selector.
+
+    Returns ``None`` for ``all``, comma lists, exclusion syntax, missing
+    selectors, and unimportable names. Imports ONLY the explicitly named
+    module via ``importlib`` — never iterates ``detectors/``. Used by the
+    two analyze entry points to feed ``route_positional_source`` with the
+    detector's REQUIRED_LOGS / OPTIONAL_LOGS metadata.
+    """
+    if not isinstance(detect, str):
+        return None
+    name = detect.strip()
+    if not name or name.lower() == "all" or "," in name or "!" in name:
+        return None
+    try:
+        import importlib
+        return importlib.import_module(f"loghunter.detectors.{name}")
+    except ImportError:
+        return None
+
+
+def _run_all_detectors(args: list[str]) -> None:
+    """Parse args and invoke runner with all enabled detectors.
+
+    Each positional in ``parsed["paths"]`` is sniff-classified into its source
+    family bucket via ``route_positional_source`` (detector_module=None for
+    detect=all / unknown selector → content-sniff → ``{origin}_dir``,
+    defaulting to ``zeek_dir`` on directory / unrecognized / OSError). The
+    per-family bucket then MERGES with any explicit ``--<family>-dir`` flag
+    inside ``_runner_kwargs``. ``scope = frozenset(touched_families)`` keeps
+    sibling source-dirs suppressed.
+    """
+    import loghunter.runner as runner
+
+    parsed = _parse_args(args, "")
+
+    if "output" in parsed:
+        get_handler(parsed["output"])
+
+    config = cfg.load(parsed.get("config"))
+
+    paths = parsed.get("paths") or []
+    if paths:
+        mod = _named_detector_module(parsed.get("detect"))
+        buckets = _build_positional_buckets(paths, detector_module=mod)
+        scope: frozenset[str] | None = frozenset(buckets) if buckets else None
+    else:
+        buckets = {}
+        scope = None
+
+    runner.run(**_runner_kwargs(
+        parsed, config, scope=scope, source_buckets=buckets,
+    ))
+
+
+def _run_single_detector(detector: str, args: list[str]) -> None:
+    """Parse args and invoke runner constrained to a single detector.
+
+    Each positional in ``parsed["paths"]`` is sniff-classified into its source
+    family bucket using the named detector module's REQUIRED_LOGS /
+    OPTIONAL_LOGS metadata (via ``route_positional_source(detector_module=mod)``).
+    The per-family bucket then MERGES with any explicit ``--<family>-dir`` flag
+    inside ``_runner_kwargs``. ``scope = frozenset(touched_families)`` keeps
+    sibling source-dirs suppressed.
+    """
+    import loghunter.runner as runner
+
+    parsed = _parse_args(args, detector)
+
+    if "output" in parsed:
+        get_handler(parsed["output"])
+
+    config = cfg.load(parsed.get("config"))
+
+    paths = parsed.get("paths") or []
+    if paths:
+        mod = _named_detector_module(detector)
+        buckets = _build_positional_buckets(paths, detector_module=mod)
+        scope: frozenset[str] | None = frozenset(buckets) if buckets else None
+    else:
+        buckets = {}
+        scope = None
+
+    runner.run(**_runner_kwargs(
+        parsed, config, detect=detector, scope=scope, source_buckets=buckets,
+    ))
+
+
+_SOURCE_DIR_KEYS = (
+    "zeek_dir", "pihole_dir", "syslog_dir", "cloudtrail_dir", "blob_path",
+)
+
+
+def _route_sniffed_path(
+    parsed: dict[str, Any],
+    path: Path,
+    result: Any,
+) -> tuple[dict[str, Any], str]:
+    """Build a per-path parsed-dict variant routing a sniffed PATH into the
+    right source-dir kwarg. Clears prior-iteration source-dir keys so a stale
+    value never leaks between paths in a fan-out loop."""
+    parsed_for_path = {
+        k: v for k, v in parsed.items() if k not in _SOURCE_DIR_KEYS
+    }
+    schema = result.schema
+    path_str = str(path)
+    if schema == "conn":
+        parsed_for_path["zeek_dir"] = path_str
+    elif schema == "dns":
+        if result.origin == "pihole":
+            parsed_for_path["pihole_dir"] = path_str
+        else:
+            parsed_for_path["zeek_dir"] = path_str
+    elif schema == "syslog":
+        # syslog is fidelity-aware: Zeek syslog.log → zeek_dir; flat
+        # rsyslog → syslog_dir. Mirrors the dns origin-split above.
+        if result.origin == "zeek":
+            parsed_for_path["zeek_dir"] = path_str
+        else:
+            parsed_for_path["syslog_dir"] = path_str
+    elif schema == "cloudtrail":
+        parsed_for_path["cloudtrail_dir"] = path_str
+    else:  # schema == "blob"
+        # blob_path is INTERNAL — synthesized post-sniff. It is NOT a flag
+        # and must NEVER appear in _FLAGS / _VERBS / help.
+        parsed_for_path["blob_path"] = path_str
+    return parsed_for_path, schema
+
+
+def _run_digest(args: list[str]) -> int:
+    """Parse args and dispatch to runner.run_digest, supporting N positionals."""
+    import loghunter.runner as runner
+    from loghunter.common.loader import sniff_format_detailed
+
+    parsed = _parse_args(args, "digest")
+
+    # Output validation: registry-first (uniform error voice), then digest's
+    # text-only rail. The spec already forbids --output for digest? No — it
+    # ALLOWS --output but digest renders text cards only.
+    out_fmt = parsed.get("output", "text")
+    get_handler(out_fmt)
+    if out_fmt != "text":
+        raise ValueError(
+            f"digest currently supports only --output=text (got {out_fmt!r})"
+        )
+
+    # Positional + source-dir combination guard. The spec allows --zeek-dir
+    # for BARE digest (no positional, single conn card from a configured
+    # source dir). With a positional present, the positional self-routes via
+    # sniff and source-dir flags would be silently overridden — reject the
+    # combination up-front so the operator sees the conflict.
+    if parsed.get("paths"):
+        for flag in ("zeek_dir", "pihole_dir", "syslog_dir", "cloudtrail_dir"):
+            if flag in parsed:
+                raise ValueError(
+                    f"digest: --{flag.replace('_', '-')} is not valid alongside "
+                    "a positional PATH (positionals self-route via sniff)"
+                )
+
+    config = cfg.load(parsed.get("config"))
+
+    paths_raw = parsed.get("paths") or []
+
+    if not paths_raw:
+        # No positional: config-driven path. Bare digest, single conn card.
+        # Output target is resolved by _digest_runner_kwargs (no fan-out
+        # involved), so the existing single-card flow is preserved verbatim.
+        try:
+            runner.run_digest(
+                **_digest_runner_kwargs(parsed, config, schema="conn")
+            )
+        except DigestEmpty as exc:
+            # Recognized-but-empty (e.g. header-only conn.log in the
+            # configured directory). The file was understood — narrate
+            # without a card and exit 0. PLACEHOLDER voice — qmail
+            # error-voice pass.
+            print(
+                f"digest: {exc.basename}: recognized as {exc.schema} "
+                "but no parseable records — skipping.",
+                file=sys.stderr,
+            )
+            return 0
+        return 0
+
+    # Fan-out path. Resolve the shared output target ONCE — never per path.
+    is_dry_run = bool(parsed.get("dry_run", False))
+    get_stream, close_stream = _build_digest_fanout_stream(
+        parsed, config, dry_run=is_dry_run,
+    )
+
+    is_multirun = len(paths_raw) > 1
+
+    rendered = empty = recognized_empty = errored = 0
+    try:
+        for raw in paths_raw:
+            path = Path(os.path.expanduser(raw))
+            if not path.exists():
+                print(f"digest: path not found: {path}", file=sys.stderr)
+                errored += 1
+                continue
+            if path.is_dir():
+                # Multi-path fan-out: silently skip a directory positional.
+                # The lone-positional case keeps the v1 contract — whole-
+                # directory positionals are rejected with an actionable
+                # stderr message and exit 1.
+                if len(paths_raw) == 1:
+                    print(
+                        f"digest: PATH must be a file, not a directory: {path}",
+                        file=sys.stderr,
+                    )
+                    errored += 1
+                continue
+            try:
+                result = sniff_format_detailed(path)
+                if result.state == "empty":
+                    print(f"{path.name} is empty. Nothing to do!")
+                    empty += 1
+                    continue
+                parsed_for_path, schema = _route_sniffed_path(
+                    parsed, path, result,
+                )
+                kwargs = _digest_runner_kwargs(
+                    parsed_for_path, config, schema=schema,
+                    resolve_output=False,
+                )
+                if schema != "blob":
+                    kwargs["fallback_blob_path"] = path
+                runner.run_digest(
+                    **kwargs,
+                    stream=get_stream(),
+                    leading_separator=(rendered > 0),
+                    show_progress=not is_multirun,
+                )
+            except DigestEmpty as exc:
+                print(
+                    f"digest: {exc.basename}: recognized as {exc.schema} "
+                    "but no parseable records — skipping.",
+                    file=sys.stderr,
+                )
+                recognized_empty += 1
+                continue
+            except (ValueError, OSError) as exc:
+                print(f"digest: {path.name}: {exc}", file=sys.stderr)
+                errored += 1
+                continue
+            rendered += 1
+    finally:
+        close_stream()
+
+    if rendered > 0:
+        return 0
+    if errored == 0:
+        return 0
+    return 1
+
+
+def _build_digest_fanout_stream(
+    parsed: dict[str, Any],
+    config: dict[str, Any],
+    dry_run: bool = False,
+) -> tuple[Any, Any]:
+    """Resolve the shared digest --out target into a lazy (get, close) pair.
+
+    Returns:
+      get_stream() — sys.stdout for stdout runs; for file targets, opens on
+        first call and returns the same handle on subsequent calls.
+      close_stream() — closes the file only if get_stream() was ever called.
+
+    --dry-run skips output resolution entirely.
+    """
+    if dry_run:
+        return (lambda: sys.stdout, lambda: None)
+
+    output_file, output_dir = _resolve_output_target(parsed, config)
+
+    if output_file is None and output_dir is None:
+        return (lambda: sys.stdout, lambda: None)
+
+    if output_file is not None:
+        dest = output_file
+    else:
+        # DIR verdict: digest_<timestamp>.txt — fixed for whole run, never
+        # derived from any input path. One code path for N=1 and N>1.
+        stamp = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
+        dest = output_dir / f"digest_{stamp}.txt"
+
+    state: dict[str, Any] = {"fh": None}
+
+    def _get_stream() -> Any:
+        if state["fh"] is None:
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            state["fh"] = dest.open("w", encoding="utf-8", newline="")
+        return state["fh"]
+
+    def _close_stream() -> None:
+        fh = state["fh"]
+        if fh is not None:
+            fh.close()
+
+    return (_get_stream, _close_stream)
+
+
+def _digest_runner_kwargs(
+    parsed: dict[str, Any],
+    config: dict[str, Any],
+    schema: str = "conn",
+    resolve_output: bool = True,
+) -> dict[str, Any]:
+    """Build the kwargs dict for runner.run_digest from parsed CLI args + config.
+
+    Source-dir overrides (``zeek_dir`` / ``pihole_dir`` / ``syslog_dir`` /
+    ``cloudtrail_dir``) flow through as RAW strings (or ``None``). The CLI
+    does NOT resolve or path-wrap them — ``loghunter.common.sources.resolve_digest_source``
+    in ``run_digest`` owns the per-schema candidate ladder, wrong-key + XOR +
+    not-configured errors, and the SOLE string→Path conversion site
+    (``_resolve_one``). Window + output target stay here.
+
+    ``blob_path`` is an INTERNAL routing key (NOT a flag) synthesized by
+    ``_route_sniffed_path``; it stays a ``Path`` and is consumed by
+    ``run_digest``'s blob branch BEFORE source resolution.
+
+    ``resolve_output=False`` is the fan-out seam: the CLI's `_run_digest`
+    has already resolved the shared `--out` target into a single TextIO
+    stream that is passed alongside, so per-path kwargs MUST NOT re-resolve.
+    """
+    _assert_all_vs_timeframe(parsed)
+
+    since, until = _resolve_timeframe(parsed)
+
+    output_file: Path | None = None
+    output_dir: Path | None = None
+    if resolve_output:
+        output_file, output_dir = _resolve_output_target(parsed, config)
+
+    cli_blob = parsed.get("blob_path")
+
+    return dict(
+        config=config,
+        # Source-dir overrides: raw strings (or None) — resolver owns Path conversion.
+        zeek_dir=parsed.get("zeek_dir"),
+        pihole_dir=parsed.get("pihole_dir"),
+        syslog_dir=parsed.get("syslog_dir"),
+        cloudtrail_dir=parsed.get("cloudtrail_dir"),
+        # blob_path is internal routing — expanduser only (no LH_ROOT, no
+        # be_like_water). The blob branch in run_digest consumes it BEFORE
+        # source resolution, so it never reaches resolve_digest_source.
+        blob_path=Path(os.path.expanduser(cli_blob)) if cli_blob else None,
+        since=since,
+        until=until,
+        output_format=parsed.get("output", "text"),
+        output_dir=output_dir,
+        output_file=output_file,
+        verbose_level=_resolve_verbose_level(parsed),
+        dry_run=bool(parsed.get("dry_run", False)),
+        load_all=bool(parsed.get("all", False)),
+        skip_confirm=bool(parsed.get("yes", False)),
+        schema=schema,
+    )
+
+
+def _run_init(args: list[str]) -> None:
+    """Validate init args via the spec, then delegate to the wizard.
+
+    init's allowed set is help-only. Standalone ``--help`` / ``-h`` is
+    short-circuited in ``_main`` BEFORE this function is invoked, so anything
+    that reaches here MUST be an empty list — any unexpected token raises
+    via the strict parser (unknown flag or wrong-verb).
+    """
+    _parse_args(args, "init")
+    from loghunter.cli_init import run_init
+    run_init()
+
+
+def _run_export(args: list[str]) -> None:
+    """Pull logs from an external system (Splunk, CloudTrail) to local files."""
+    from loghunter.exporters import run_export
+
+    parsed = _parse_args(args, "export")
+
+    # Timeframe: pass None when no flags given — exporter applies its own default
+    since, until = _resolve_timeframe(parsed, now=datetime.now().astimezone())
+
+    config = cfg.load(parsed.get("config"))
+
+    positionals: list[str] = parsed.get("paths") or []
+
+    # Disambiguate: first positional is a backend name if it matches a known backend
+    _KNOWN_EXPORT_BACKENDS = {"splunk", "cloudtrail"}
+    if positionals and positionals[0] in _KNOWN_EXPORT_BACKENDS:
+        backend: str | None = positionals[0]
+        query_names = positionals[1:]
+    else:
+        backend = None
+        query_names = positionals
+
+    # Pass the raw CLI string (preserving any trailing slash) — be_like_water
+    # decides file vs directory inside the export pipeline.
+    out_str = parsed.get("out") if "out" in parsed else None
+
+    # Export collapses to a single bool: -vv on export == -v (no level-2
+    # surface). The export pipeline keeps its bool internally; the CLI
+    # collapses at the seam.
+    run_export(
+        config=config,
+        backend=backend,
+        query_names=query_names,
+        since=since,
+        until=until,
+        out=out_str,
+        verbose=(_resolve_verbose_level(parsed) >= 1),
+        skip_confirm=bool(parsed.get("yes", False)),
+    )