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

loghunter/cli_init.py

@@ -0,0 +1,567 @@
+"""First-run setup wizard.
+
+CLI-INTERNAL split off ``loghunter/cli.py`` — first-run UX REMAINS CLI-layer
+ownership. This module owns the wizard; ``cli.py`` keeps dispatch and arg
+validation. Nothing here imports detectors, runner, or outputs.
+
+The wizard mostly works by hitting Enter: it LOOKS before it asks (detect +
+profile what's on disk) and NEVER clobbers config a user already set. Path
+profiling is glob + stat ONLY — never reads a log line.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import tomllib
+from datetime import datetime, timedelta
+from pathlib import Path
+
+# ── detection ─────────────────────────────────────────────────────────────────
+#
+# Detection looks at conventional public paths; nothing here ever reads a log
+# LINE — stat + glob only. Constants are module-level so flow tests can
+# monkeypatch them off the developer's real filesystem.
+
+_ZEEK_CANDIDATES: tuple[str, ...] = (
+    "/var/log/zeek",
+    "/opt/zeek/logs",
+    "/usr/local/zeek/logs",
+    "/nsm/zeek/logs",
+)
+# Each entry: (probe path, candidate_dir to register if probe matches). The
+# probe may be a literal file or an absolute glob ("/dir/*.log").
+_PIHOLE_CANDIDATES: tuple[tuple[str, str], ...] = (
+    ("/var/log/pihole/pihole.log", "/var/log/pihole"),
+    ("/var/log/pihole.log",        "/var/log"),
+    ("/var/log/pihole/*.log",      "/var/log/pihole"),
+)
+_SYSLOG_CANDIDATE: str = "/var/log"
+
+# Zeek family globs drive the {logs} fill and the size sum.
+_ZEEK_GLOBS: tuple[str, ...] = (
+    "conn*.log*", "dns*.log*", "ssl*.log*",
+    "http*.log*", "weird*.log*", "notice*.log*",
+)
+# Pi-hole stays narrow even when the candidate dir is /var/log — we profile
+# only the Pi-hole file so unrelated syslog files don't inflate the size.
+_PIHOLE_GLOB: str = "pihole.log*"
+# Syslog mirrors the detector's OPTIONAL_LOGS glob so the profile honestly
+# previews what will be analyzed.
+_SYSLOG_GLOB: str = "*.log*"
+
+_PROFILE_FILE_CAP: int = 5000
+_DOCS_URL: str = "https://github.com/spiralbend/loghunter"
+
+
+def _detect_zeek() -> str | None:
+    """Probe conventional Zeek log dirs; first hit with conn*.log* wins, else
+    the first dir that has any *.log*. Returns the dir path or None."""
+    fallback: str | None = None
+    for cand in _ZEEK_CANDIDATES:
+        p = Path(cand)
+        try:
+            if not p.is_dir():
+                continue
+            if any(p.glob("conn*.log*")):
+                return cand
+            if fallback is None and any(p.glob("*.log*")):
+                fallback = cand
+        except OSError:
+            continue
+    return fallback
+
+
+def _detect_pihole() -> str | None:
+    """Walk pi-hole probes; return the candidate dir of the first hit."""
+    for probe, candidate_dir in _PIHOLE_CANDIDATES:
+        try:
+            if "*" in probe:
+                # Path.glob walks the receiver — for an absolute glob we must
+                # split (parent, pattern) and glob from the parent directory.
+                parent = Path(probe).parent
+                pattern = Path(probe).name
+                if parent.is_dir() and any(parent.glob(pattern)):
+                    return candidate_dir
+            else:
+                if Path(probe).is_file():
+                    return candidate_dir
+        except OSError:
+            continue
+    return None
+
+
+def _detect_syslog() -> str | None:
+    """Return the syslog candidate dir if it exists, else None."""
+    try:
+        return _SYSLOG_CANDIDATE if Path(_SYSLOG_CANDIDATE).is_dir() else None
+    except OSError:
+        return None
+
+
+def _human_bytes(n: int) -> str:
+    """Format a byte count as `~6 GB` / `~340 MB` / `~12 KB`. The `~` reflects
+    that the count is glob-scoped, not whole-dir."""
+    if n < 1024:
+        return f"~{n} B"
+    if n < 1024 ** 2:
+        return f"~{n // 1024} KB"
+    if n < 1024 ** 3:
+        return f"~{n // (1024 ** 2)} MB"
+    if n < 1024 ** 4:
+        return f"~{n // (1024 ** 3)} GB"
+    return f"~{n // (1024 ** 4)} TB"
+
+
+def _fresh_bucket(delta: timedelta) -> str:
+    """Map an age delta to Dave's relative-time phrasing."""
+    seconds = delta.total_seconds()
+    if seconds < 3600:
+        return "updated just now"
+    if seconds < 86_400:
+        return "fresh today"
+    if seconds < 7 * 86_400:
+        return "active this week"
+    days = int(seconds // 86_400)
+    if seconds < 30 * 86_400:
+        return f"last activity ~{days} days ago"
+    if seconds < 60 * 86_400:
+        weeks = days // 7
+        return f"but it looks stale — nothing new in ~{weeks} weeks"
+    months = days // 30
+    return f"but it looks stale — nothing new in ~{months} months"
+
+
+def _profile_dir(
+    path: str,
+    globs: tuple[str, ...],
+    *,
+    logs_label: str | None,
+    now: datetime | None = None,
+) -> dict | None:
+    """Stat + glob the candidate dir; return a profile dict or None (no-data).
+
+    Permission-tolerant: a single file's stat raising OSError is silently
+    skipped. The dir not existing or no files matching returns None — the
+    caller's "reduced dialogue form" branch."""
+    p = Path(path).expanduser()
+    try:
+        if not p.is_dir():
+            return None
+    except OSError:
+        return None
+
+    matched: list[Path] = []
+    families_present: list[str] = []  # zeek family order, first-seen
+    bounded = False
+    try:
+        for glob in globs:
+            family = glob.split("*", 1)[0].rstrip(".")  # "conn*.log*" → "conn"
+            family_hit = False
+            for f in p.glob(glob):
+                matched.append(f)
+                family_hit = True
+                if len(matched) >= _PROFILE_FILE_CAP:
+                    bounded = True
+                    break
+            if family_hit and family and family not in families_present:
+                families_present.append(family)
+            if bounded:
+                break
+    except OSError:
+        return None
+
+    total = 0
+    max_mtime: float | None = None
+    for f in matched:
+        try:
+            st = f.stat()
+        except OSError:
+            continue
+        total += st.st_size
+        if max_mtime is None or st.st_mtime > max_mtime:
+            max_mtime = st.st_mtime
+
+    if not matched or total == 0 or max_mtime is None:
+        return None
+
+    now = now or datetime.now()
+    delta = now - datetime.fromtimestamp(max_mtime)
+
+    if logs_label is not None:
+        logs = logs_label
+    elif families_present:
+        if len(families_present) <= 2:
+            logs = " + ".join(families_present)
+        else:
+            logs = ", ".join(families_present)
+    else:
+        logs = ""
+
+    return {
+        "size_bytes": total,
+        "size_str": _human_bytes(total),
+        "fresh_str": _fresh_bucket(delta),
+        "logs": logs,
+        "bounded": bounded,
+    }
+
+
+# ── TOML serialization ────────────────────────────────────────────────────────
+
+_TOML_FORBIDDEN_RE = re.compile(r'[\x00-\x1f\x7f]')
+
+
+def _toml_str(value: str) -> str:
+    """Serialize a path value as a TOML string. Literal form when possible
+    (single-quoted, no escapes); basic form when the value contains a single
+    quote. Control characters are rejected — silently writing invalid TOML
+    is worse than asking the user to retype the path."""
+    if _TOML_FORBIDDEN_RE.search(value):
+        raise ValueError(
+            "loghunter init: path contains a control character that cannot "
+            f"be written to TOML: {value!r}"
+        )
+    if "'" not in value:
+        return f"'{value}'"
+    escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{escaped}"'
+
+
+# ── Section-bound keyed upsert ────────────────────────────────────────────────
+#
+# The four managed keys (root, zeek_dir, pihole_dir, syslog_dir) are rewritten
+# ONLY inside the [loghunter] table span. A token appearing in any other
+# stanza, a comment outside the span, or even a [loghunter.subtable] is never
+# matched — that IS the non-clobber guarantee.
+
+_LOGHUNTER_HEADER_RE = re.compile(r'^\[loghunter\]\s*(?:#.*)?$', re.MULTILINE)
+_MANAGED_KEYS: tuple[str, ...] = ("root", "zeek_dir", "pihole_dir", "syslog_dir")
+
+
+def _loghunter_span(text: str) -> tuple[int, int, int] | None:
+    """Locate the [loghunter] table span: (header_start, body_start, body_end).
+
+    body runs from the line AFTER the header to the line BEFORE the next
+    `^[` section header, or EOF. Returns None when the header is absent."""
+    m = _LOGHUNTER_HEADER_RE.search(text)
+    if m is None:
+        return None
+    header_start = m.start()
+    # body starts after the header line's trailing newline
+    nl = text.find("\n", m.end())
+    body_start = nl + 1 if nl != -1 else len(text)
+    # body ends at the next ^[ section header found after body_start
+    rest_offset = body_start
+    next_header_re = re.compile(r'^\[', re.MULTILINE)
+    nh = next_header_re.search(text, rest_offset)
+    body_end = nh.start() if nh else len(text)
+    return (header_start, body_start, body_end)
+
+
+def _upsert_loghunter_key(
+    text: str, key: str, value: str | None, *, fresh: bool,
+) -> str:
+    """Keyed transform inside the [loghunter] table span.
+
+    value is None        — SKIPPED. fresh=True comments any active line for
+                            the key; fresh=False is a strict no-op (never
+                            touch a user-set value).
+    value is a string    — PROVIDED. Upsert active line inside span. value=""
+                            is honored (the explicit-empty-root case).
+    """
+    span = _loghunter_span(text)
+    if span is None:
+        # Defensive — the shipped example always ships a header. Prepend one
+        # so the upsert has a place to land.
+        text = "[loghunter]\n" + text
+        span = _loghunter_span(text)
+        assert span is not None
+    header_start, body_start, body_end = span
+    body = text[body_start:body_end]
+
+    active_re = re.compile(rf'^{re.escape(key)}\s*=.*$', re.MULTILINE)
+    commented_re = re.compile(rf'^#\s*{re.escape(key)}\s*=.*$', re.MULTILINE)
+
+    if value is not None:
+        new_line = f"{key} = {_toml_str(value)}"
+        # Active match wins over a commented sample — otherwise a base shaped
+        # like `# zeek_dir = "/default"\nzeek_dir = "/custom"` produces
+        # duplicate active keys (the commented line gets uncommented while
+        # the existing active line remains, invalidating the TOML).
+        m = active_re.search(body) or commented_re.search(body)
+        if m is not None:
+            new_body = body[:m.start()] + new_line + body[m.end():]
+        else:
+            # Insert directly after the header line. body_start is already
+            # past the header newline, so prepending here = post-header.
+            new_body = new_line + "\n" + body
+        return text[:body_start] + new_body + text[body_end:]
+
+    # SKIPPED branch.
+    if not fresh:
+        return text  # never touch a user-set value
+    m = re.search(rf'^(?P<key>{re.escape(key)}\s*=.*)$', body, re.MULTILINE)
+    if m is None:
+        return text  # active line not present; nothing to comment
+    line_start = m.start()
+    new_body = body[:line_start] + "# " + body[line_start:]
+    return text[:body_start] + new_body + text[body_end:]
+
+
+# ── Wizard dialogue ───────────────────────────────────────────────────────────
+
+def _print_intro(existing_basis: bool) -> None:
+    print("OK, let's find your logs.")
+    if existing_basis:
+        print("Found ~/.loghunter/, using that as basis (non-destructive)")
+    print()
+
+
+def _print_zeek_found(path: str, profile: dict | None) -> None:
+    if profile is not None:
+        print(f"Found Zeek at {path}.")
+        print(f"{profile['logs']}, {profile['size_str']}, {profile['fresh_str']}. Use this?")
+    else:
+        # No-data reduced form: single-line headline per the Rev 2 prompt.
+        print(f"Found Zeek at {path}. Use this?")
+    print("[Enter = yes  ·  type a path  ·  s = skip]")
+
+
+def _print_zeek_not_found() -> None:
+    print("Didn't find Zeek. You might like it: https://zeek.org")
+    print("If it's just hiding, tell me where.")
+    print("[Enter = skip  ·  type a path]")
+
+
+def _print_pihole_found(path: str, profile: dict | None) -> None:
+    if profile is not None:
+        print(f"Found Pi-hole at {path}.")
+        print(f"{profile['size_str']} of query logs, {profile['fresh_str']}. Use this?")
+    else:
+        # No-data reduced form: single-line headline per the Rev 2 prompt.
+        print(f"Found Pi-hole at {path}. Use this?")
+    print("[Enter = yes  ·  type a path  ·  s = skip]")
+
+
+def _print_pihole_not_found() -> None:
+    print("Pi-hole seems to be absent. Worth a look: https://pi-hole.net")
+    print("Point me at the logs if they're elsewhere.")
+    print("[Enter = skip  ·  type a path]")
+
+
+def _print_syslog(path: str, profile: dict | None) -> None:
+    if profile is not None:
+        print(f"syslog is where you'd expect… {path} — {profile['size_str']}, {profile['fresh_str']}.")
+    else:
+        print(f"syslog is where you'd expect… {path}.")
+    print("Use this?  [Enter = yes  ·  type a path  ·  s = skip]")
+
+
+def _print_gate() -> None:
+    print("You should provide at least one: Zeek, Pi-hole, or syslog.")
+    print("Or you can point loghunter at individual files. Up to you.")
+    print("[r = redo  ·  Enter = skip]")
+
+
+def _print_root_prompt(default_root: str) -> None:
+    print("Last thing: where should LogHunter keep what it produces — exports and reports?")
+    print(f"[Enter = {default_root}]")
+
+
+def _print_confirm(active_sources: list[tuple[str, str]], root: str) -> None:
+    if active_sources:
+        sources_line = ", ".join(f"{label} ({path})" for label, path in active_sources)
+    else:
+        sources_line = "(none — pass files on the command line)"
+    print("Done — settings written to ~/.loghunter/config.toml.")
+    print(f"  reading:  {sources_line}")
+    print(f"  data:     {root}")
+    print()
+    print(f"LogHunter documentation lives here: {_DOCS_URL}")
+    print("Or just run `loghunter` for a quick-start TL;DR.")
+    print()
+    print("Good hunting!")
+
+
+# ── Flow helpers ──────────────────────────────────────────────────────────────
+
+def _ask_source(found_path: str | None, found_printer, not_found_printer) -> str | None:
+    """Drive one source prompt. Returns the chosen path or None (skipped)."""
+    if found_path is not None:
+        found_printer()
+        answer = input("> ").strip()
+        if answer == "":
+            return found_path
+        if answer.lower() in ("s", "skip"):
+            return None
+        return os.path.expanduser(answer)
+    # NOT FOUND path
+    not_found_printer()
+    answer = input("> ").strip()
+    if answer == "" or answer.lower() in ("s", "skip"):
+        return None
+    return os.path.expanduser(answer)
+
+
+def _read_existing_config_for_root(
+    target: Path,
+) -> tuple[bytes | None, str | None, dict | None]:
+    """Read an existing config file. Returns (raw_bytes, decoded_text,
+    parsed-loghunter-dict). Bytes are preserved verbatim for `.bak`
+    (read_text translates CRLF→LF under universal newlines, which would
+    break the non-clobber guarantee for Windows-line-ending files)."""
+    if not target.exists():
+        return (None, None, None)
+    try:
+        raw = target.read_bytes()
+    except OSError as exc:
+        raise ValueError(
+            f"loghunter init: cannot read existing config at {target}: {exc}"
+        ) from exc
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise ValueError(
+            f"loghunter init: existing config at {target} is not UTF-8: {exc}"
+        ) from exc
+    try:
+        parsed = tomllib.loads(text)
+    except tomllib.TOMLDecodeError as exc:
+        raise ValueError(
+            f"loghunter init: existing config at {target} is not valid TOML: {exc}"
+        ) from exc
+    return (raw, text, parsed.get("loghunter", {}))
+
+
+def _load_example_text() -> str:
+    """Return the shipped config_example.toml contents."""
+    try:
+        import importlib.resources
+        pkg_data = importlib.resources.files("loghunter") / "data"
+        return (pkg_data / "config_example.toml").read_text(encoding="utf-8")
+    except Exception:
+        example_path = Path(__file__).parent / "data" / "config_example.toml"
+        return example_path.read_text(encoding="utf-8")
+
+
+def run_init() -> None:
+    """Detection-driven, non-clobbering wizard for the first-run config.
+
+    Public entry point — ``cli.py`` validates argv via ``_parse_args(args,
+    "init")`` (allowed set is help-only; standalone ``--help``/``-h`` is
+    short-circuited before this function is invoked) and then delegates here.
+    """
+    target = Path("~/.loghunter/config.toml").expanduser()
+    existing_bytes, existing_text, existing_lh = _read_existing_config_for_root(target)
+    existing_basis = existing_bytes is not None
+    base_text = existing_text if existing_basis else _load_example_text()
+    fresh = not existing_basis
+
+    _print_intro(existing_basis)
+
+    # Run the three source prompts in order; on gate-redo we re-loop.
+    while True:
+        zeek_path = _detect_zeek()
+        zeek_profile = (
+            _profile_dir(zeek_path, _ZEEK_GLOBS, logs_label=None) if zeek_path else None
+        )
+        zeek_answer = _ask_source(
+            zeek_path,
+            lambda: _print_zeek_found(zeek_path, zeek_profile),
+            _print_zeek_not_found,
+        )
+        print()
+
+        pihole_path = _detect_pihole()
+        pihole_profile = (
+            _profile_dir(pihole_path, (_PIHOLE_GLOB,), logs_label="query logs")
+            if pihole_path else None
+        )
+        pihole_answer = _ask_source(
+            pihole_path,
+            lambda: _print_pihole_found(pihole_path, pihole_profile),
+            _print_pihole_not_found,
+        )
+        print()
+
+        syslog_path = _detect_syslog()
+        if syslog_path is not None:
+            syslog_profile = _profile_dir(syslog_path, (_SYSLOG_GLOB,), logs_label=None)
+            _print_syslog(syslog_path, syslog_profile)
+            syslog_input = input("> ").strip()
+            if syslog_input == "":
+                syslog_answer: str | None = syslog_path
+            elif syslog_input.lower() in ("s", "skip"):
+                syslog_answer = None
+            else:
+                syslog_answer = os.path.expanduser(syslog_input)
+        else:
+            # Treat absent /var/log as a no-found case (extremely rare in
+            # practice). Reuse the Zeek not-found shape for shape consistency.
+            print("syslog isn't where I'd expect — point me at the logs if they're elsewhere.")
+            print("[Enter = skip  ·  type a path]")
+            answer = input("> ").strip()
+            syslog_answer = os.path.expanduser(answer) if answer else None
+        print()
+
+        if zeek_answer is None and pihole_answer is None and syslog_answer is None:
+            _print_gate()
+            gate = input("> ").strip().lower()
+            if gate == "r":
+                continue  # re-loop the three source prompts
+        break
+
+    # Root default: existing config's explicit root wins (including ""); else
+    # the new live default ~/.loghunter.
+    default_root = "~/.loghunter"
+    if existing_lh is not None and "root" in existing_lh:
+        default_root = existing_lh["root"]
+    _print_root_prompt(default_root)
+    root_input = input("> ").strip()
+    root_value = default_root if root_input == "" else os.path.expanduser(root_input)
+    print()
+
+    # Write `.bak` BEFORE any transformation when re-initing an existing file.
+    # Backup the RAW bytes verbatim — text-mode round-trip would translate
+    # CRLF→LF on the way in and leave the .bak non-identical to the original.
+    target.parent.mkdir(parents=True, exist_ok=True)
+    if existing_basis:
+        bak_path = target.with_suffix(".toml.bak")
+        try:
+            bak_path.write_bytes(existing_bytes)
+        except OSError as exc:
+            raise ValueError(
+                f"loghunter init: cannot write backup at {bak_path}: {exc}"
+            ) from exc
+
+    text = base_text
+    for key, val in (
+        ("root", root_value),
+        ("zeek_dir", zeek_answer),
+        ("pihole_dir", pihole_answer),
+        ("syslog_dir", syslog_answer),
+    ):
+        text = _upsert_loghunter_key(text, key, val, fresh=fresh)
+
+    # Bytes-out symmetric with bytes-in: write_text would platform-translate
+    # the newline boundary on Windows. write_bytes preserves the byte stream.
+    target.write_bytes(text.encode("utf-8"))
+
+    active: list[tuple[str, str]] = []
+    if zeek_answer is not None:
+        active.append(("Zeek", zeek_answer))
+    if pihole_answer is not None:
+        active.append(("Pi-hole", pihole_answer))
+    if syslog_answer is not None:
+        active.append(("syslog", syslog_answer))
+    _print_confirm(active, root_value)
+
+
+# Compat shim — pre-extraction tests called `cli._run_init([])`. The new entry
+# is ``run_init()`` (cli.py validates argv via ``_parse_args(args, "init")``
+# before delegating). Tests that drive the wizard end-to-end keep working.
+def _run_init(args: list[str] | None = None) -> None:
+    """Wrapper that preserves the pre-extraction call shape for tests."""
+    del args
+    run_init()

loghunter/common/__init__.py

@@ -0,0 +1 @@
+"""Common utilities shared across detectors and output handlers."""