ensign-scan 0.1.0__py3-none-any.whl

ensign_scan/__init__.py

@@ -0,0 +1 @@
+"""Ensign — file hashing and ClamAV scanning with a change-tracking database."""

ensign_scan/clamd.py

@@ -0,0 +1,186 @@
+"""Minimal clamd unix-socket client, plus a clamscan CLI fallback."""
+from __future__ import annotations
+
+import re
+import shutil
+import socket
+import subprocess
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+from .models import ScanStatus
+
+_FOUND_RE = re.compile(r":\s+(.+?)\s+FOUND")
+
+# clamd's wording for "file too large to scan" is inconsistent across
+# versions -- some report it plainly, others substitute the misleading
+# "Can't allocate memory" for the exact same underlying condition
+# (a known, longstanding clamd quirk, not an actual OOM).
+_SIZE_LIMIT_MARKERS = ("size limit exceeded", "size limit reached", "can't allocate memory")
+
+
+def is_size_limit_error(raw: str) -> bool:
+    """True if a clamd response indicates a size-limit rejection, not a
+    genuine scan failure -- these call for a different remedy (raise the
+    limit, or fall back to the clamscan CLI) than a real error does."""
+    text = raw.lower()
+    return any(marker in text for marker in _SIZE_LIMIT_MARKERS)
+
+
+_PERMISSION_MARKERS = ("access denied", "permission denied")
+
+
+def is_permission_error(raw: str) -> bool:
+    """True if a clamd response indicates it couldn't read the file due
+    to permissions -- as opposed to a size limit or a genuine scan
+    failure. Used to distinguish "clamd was refused" from "clamd tried
+    and something went wrong."""
+    text = raw.lower()
+    return any(marker in text for marker in _PERMISSION_MARKERS)
+
+
+def clamscan_cli_available() -> bool:
+    return shutil.which("clamscan") is not None
+
+
+def scan_with_clamscan_cli(filepath: Path | str, timeout: float = 180.0) -> "ScanOutcome":
+    """Fall back to the clamscan CLI for one file, bypassing clamd's
+    configured MaxFileSize/MaxScanSize entirely via explicit overrides.
+
+    Only meant for files the daemon has already rejected as too large.
+    Each invocation loads the whole signature database fresh -- seconds,
+    not milliseconds -- so this is not something to run routinely.
+    """
+    try:
+        result = subprocess.run(
+            ["clamscan", "--no-summary", "--infected",
+             "--max-filesize=0", "--max-scansize=0", str(filepath)],
+            capture_output=True, text=True, timeout=timeout,
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        return ScanOutcome(ScanStatus.ERROR, f"clamscan CLI fallback failed: {exc}")
+
+    output = result.stdout.strip()
+    if result.returncode == 0:
+        return ScanOutcome(ScanStatus.CLEAN, output or "OK (clamscan CLI fallback)")
+    if result.returncode == 1:
+        match = _FOUND_RE.search(output)
+        threat = match.group(1) if match else "Unknown"
+        return ScanOutcome(ScanStatus.INFECTED, output, threat)
+    return ScanOutcome(ScanStatus.ERROR, output or f"clamscan CLI exited {result.returncode}")
+
+
+@dataclass(frozen=True)
+class ScanOutcome:
+    status: ScanStatus
+    raw: str
+    threat_name: str | None = None
+
+
+class ClamdClient:
+    def __init__(self, socket_path: str, timeout: float = 300.0):
+        self.socket_path = socket_path
+        self.timeout = timeout
+
+    def _command(self, command: str) -> str:
+        """Send one command and read the full reply.
+
+        clamd terminates replies with a newline; a single recv(4096)
+        can truncate long responses, so read until the terminator.
+        """
+        with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as sock:
+            sock.settimeout(self.timeout)
+            sock.connect(self.socket_path)
+            sock.sendall(f"n{command}\n".encode())
+            chunks: list[bytes] = []
+            while True:
+                data = sock.recv(4096)
+                if not data:
+                    break
+                chunks.append(data)
+                if data.endswith(b"\n"):
+                    break
+        return b"".join(chunks).decode().strip()
+
+    def ping(self) -> bool:
+        """True if clamd is up and answering on the socket."""
+        try:
+            return self._command("PING") == "PONG"
+        except OSError:
+            return False
+
+    def max_threads(self) -> int | None:
+        """clamd's own MaxThreads limit, read from its STATS output.
+
+        Sending more concurrent scans than this just queues inside the
+        daemon (and overflows MaxQueue under sustained load), so it is
+        the true ceiling for useful worker-pool size.
+        """
+        try:
+            stats = self._command("STATS")
+        except OSError:
+            return None
+        match = re.search(r"THREADS:.*?\bmax\s+(\d+)", stats)
+        return int(match.group(1)) if match else None
+
+    def signature_version(self) -> int | None:
+        """The loaded signature database's version number, via VERSION.
+
+        The middle field of "ClamAV <engine>/<sig-version>/<build date>"
+        (e.g. 27455). It rises with each database release, so comparing two
+        of them says how many releases apart two scans were. None if clamd
+        is unreachable or the response doesn't parse -- "unknown", not 0.
+        """
+        try:
+            version = self._command("VERSION")
+        except OSError:
+            return None
+        parts = version.split("/")
+        if len(parts) < 3:
+            return None
+        try:
+            return int(parts[-2])
+        except ValueError:
+            return None
+
+    def signature_age_days(self) -> int | None:
+        """Days since the loaded signature database was built, via VERSION.
+
+        Response format: "ClamAV <engine>/<sig-version>/<build date>",
+        e.g. "ClamAV 1.2.0/27455/Wed Jan 15 08:12:00 2026". Returns None
+        if clamd is unreachable or the response doesn't parse -- callers
+        should treat that as "unknown," not "stale."
+        """
+        try:
+            version = self._command("VERSION")
+        except OSError:
+            return None
+        parts = version.split("/")
+        if len(parts) < 3:
+            return None
+        date_str = parts[-1].strip()
+        try:
+            built = datetime.strptime(date_str, "%a %b %d %H:%M:%S %Y")
+        except ValueError:
+            return None
+        return (datetime.now() - built).days
+
+    def scan(self, filepath: Path | str) -> ScanOutcome:
+        """Scan one file via clamd's SCAN command.
+
+        clamd reads the file itself, so it needs read permission on the
+        path (see the ACL notes in the README).
+        """
+        try:
+            response = self._command(f"SCAN {filepath}")
+        except OSError as exc:
+            return ScanOutcome(ScanStatus.ERROR, f"Scan error: {exc}")
+
+        if response.endswith("OK"):
+            return ScanOutcome(ScanStatus.CLEAN, response)
+        if "FOUND" in response:
+            match = _FOUND_RE.search(response)
+            threat = match.group(1) if match else "Unknown"
+            return ScanOutcome(ScanStatus.INFECTED, response, threat)
+        return ScanOutcome(ScanStatus.ERROR, response)

ensign_scan/cli.py

@@ -0,0 +1,174 @@
+"""Ensign command-line entry point (the `ensign-scan` command).
+
+All side effects (greeting, logging setup, the scan itself) happen in
+main(), not at import time, so the package can be imported by tests or
+other scripts without launching a full system scan.
+"""
+from __future__ import annotations
+
+import sys
+
+if sys.version_info < (3, 11):
+    v = sys.version_info
+    print(f"Ensign requires Python 3.11 or newer (found {v.major}.{v.minor}).")
+    print("It uses the standard-library 'tomllib' module for config parsing.")
+    raise SystemExit(1)
+
+import argparse
+import time
+
+from rich import print
+
+from ensign_scan.config import HOME, HOSTNAME, Config, ensure_default_config
+from ensign_scan import explanations, logsetup, notify, pacman, secrets
+from ensign_scan.runlock import AlreadyRunning, RunLock
+from ensign_scan.reports import error_summary, list_infected, pacman_report, scan_summary, suggest_fixes, unreadable_report
+from ensign_scan.scanner import Scanner
+
+EXIT_BUSY = 75  # sysexits EX_TEMPFAIL: another Ensign holds the lock; try again later
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Hash and ClamAV-scan the system.")
+    parser.add_argument("targets", nargs="*",
+                        help="Directories to scan (default: scan_targets from config)")
+    parser.add_argument("--config", metavar="PATH",
+                        help="Config file (default: ~/.config/ensign/config.toml)")
+    parser.add_argument("--no-scan", action="store_true",
+                        help="Hash and record files without ClamAV scanning")
+    parser.add_argument("--skip-rescans", action="store_true",
+                        help="Skip the infected/error/stale rescan passes")
+    parser.add_argument("--purge-missing", action="store_true",
+                        help="Remove DB records for files that no longer exist, then exit")
+    parser.add_argument("--rescan-errors", action="store_true",
+                        help="Retry only files currently marked ERROR, then exit (no full scan)")
+    parser.add_argument("--verify-pacman", action="store_true",
+                        help="Check installed files against pacman's records, then exit (Arch only, can be slow)")
+    parser.add_argument("--suggest-fixes", action="store_true",
+                        help="Print suggested setfacl fixes for current errors, then exit (no full scan). "
+                             "Scoped to any targets given.")
+    return parser.parse_args()
+
+
+def setup_logging(config: Config) -> None:
+    logsetup.setup(config)
+
+
+def greet(config: Config) -> None:
+    print()
+    print(f" Greetings, {HOME.name}!")
+    print("-" * 71)
+    print(" I, Ensign, will start scanning your system shortly…")
+    print(f" Host:     {HOSTNAME}")
+    print(f" Config:   {config.source}")
+    print(f" Database: {config.data_dir / 'system.db'}")
+    print("-" * 71)
+
+
+def main() -> int:
+    args = parse_args()
+    if not args.config:
+        ensure_default_config()
+    config = Config.load(args.config)
+    secrets.load_custom(config)
+    explanations.load_custom(config)
+    setup_logging(config)
+
+    # The read-only reports never write to the database, so they don't need
+    # the lock and can run alongside a scan.
+    if args.verify_pacman or args.suggest_fixes:
+        return run(args, config)
+
+    lock = RunLock(config.data_dir / "ensign.lock")
+    try:
+        lock.acquire()
+    except AlreadyRunning as busy:
+        who = f"pid {busy.holder_pid}" if busy.holder_pid else "another process"
+        print(f"[yellow]Ensign is already running ({who}). Not starting a second one.[/yellow]")
+        print(f"  Lock: {busy.path}")
+        return EXIT_BUSY
+    try:
+        return run(args, config)
+    finally:
+        lock.release()
+
+
+def run(args: argparse.Namespace, config: Config) -> int:
+    greet(config)
+
+    scanner = Scanner(config)
+    if args.purge_missing:
+        scanner.purge_missing()
+        return 0
+    if args.rescan_errors:
+        if not scanner.clamd.ping():
+            print("[red]✗ clamd is not answering on its socket.[/red]")
+            return 1
+        scanner.rescan_errors()
+        return 0
+    if args.verify_pacman:
+        pacman_report(scanner.engine, pacman.verify_all())
+        return 0
+    if args.suggest_fixes:
+        suggest_fixes(scanner.engine, paths=args.targets or None)
+        return 0
+    auto = " (auto)" if config.max_workers <= 0 else ""
+    print(f" Workers:  {scanner.workers}{auto}")
+    scan = not args.no_scan
+
+    if scan and not scanner.clamd.ping():
+        print("[red]✗ clamd is not answering on its socket.[/red]")
+        print(f"  Socket: {config.clamd_socket}")
+        print("  Start it with: sudo systemctl start clamav-daemon")
+        return 1
+    if scan:
+        print("[green]✓ clamd is up.[/green]")
+        if config.signature_max_age_days > 0:
+            sig_age = scanner.clamd.signature_age_days()
+            if sig_age is not None and sig_age > config.signature_max_age_days:
+                print(f"[yellow]! Virus signatures are {sig_age} days old "
+                      f"(threshold: {config.signature_max_age_days}). Run: sudo freshclam[/yellow]")
+        print()
+
+    targets = args.targets or config.scan_targets
+    start = time.time()
+    print("=== Starting Scan ===")
+    unreadable: dict[str, str] = {}
+    missing: set[str] = set()
+    for target in targets:
+        print(f"\nChecking [violet]{target}[/violet]:")
+        stats = scanner.scan_tree(target, scan=scan)
+        unreadable.update(stats.unreadable_dirs)
+        missing |= stats.missing
+
+    print(f"\nExecution time: {time.time() - start:.1f} seconds")
+
+    if scan and not args.skip_rescans:
+        print("\n=== Processing Rescans ===")
+        scanner.rescan_infected()
+        scanner.rescan_errors()
+        scanner.rescan_stale()
+
+    summary = scan_summary(scanner.engine, paths=args.targets or None)
+    if missing:
+        print(f"Broken symlinks / vanished files skipped: {len(missing)}")
+    error_summary(scanner.engine, paths=args.targets or None)
+    unreadable_report(unreadable)
+    infected = list_infected(scanner.engine, paths=args.targets or None)
+    suggest_fixes(scanner.engine, paths=args.targets or None)
+    notify.send(summary, infected, config.infected_alert_seconds,
+                only_when_gaming=config.infected_alert_only_while_gaming,
+                interactive=sys.stdin.isatty(),
+                state_path=config.data_dir / "alert_state.json")
+
+    print("\n=== All Scans Finished ===")
+    print("-" * 71)
+    print(" All finished.")
+    print(" Feel free to call upon me again.")
+    print("     — Ensign")
+    print()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ensign_scan/config.py

@@ -0,0 +1,325 @@
+"""Configuration for Ensign.
+
+Design for multi-machine use:
+
+  * The code contains NO machine-specific values. Everything lives in a
+    TOML file, so any user on any box gets sane defaults out of the box.
+  * Config search order: --config flag > $ENSIGN_CONFIG > 
+    ~/.config/ensign/config.toml > built-in defaults.
+  * Per-machine differences go in [hosts.<hostname>] sections of the
+    SAME file, so you can sync one config across all your machines and
+    each one picks up its own overrides.
+  * "~" in the config file always means the *invoking* user's home,
+    even under sudo (resolved via SUDO_USER + the passwd database, so
+    it also works for homes outside /home).
+"""
+from __future__ import annotations
+
+import os
+import pwd
+import socket
+import tomllib
+from dataclasses import dataclass, field, fields
+from pathlib import Path
+
+
+# ----------------------------------------------------------------------
+# Identity: who is really running this, and on which machine?
+# ----------------------------------------------------------------------
+
+def real_home() -> Path:
+    """Home directory of the invoking user, even under sudo.
+
+    Path.home() returns /root under sudo. SUDO_USER preserves the real
+    account, and the passwd database gives its true home directory —
+    no assumption that homes live under /home.
+    """
+    sudo_user = os.environ.get("SUDO_USER")
+    if sudo_user:
+        try:
+            return Path(pwd.getpwnam(sudo_user).pw_dir)
+        except KeyError:
+            pass  # SUDO_USER set but unknown; fall through
+    return Path.home()
+
+
+HOME = real_home()
+HOSTNAME = socket.gethostname()
+
+DEFAULT_DATA_DIR = HOME / ".local" / "share" / "ensign"
+DEFAULT_CONFIG_PATH = HOME / ".config" / "ensign" / "config.toml"
+
+_DEFAULT_TARGETS = ("~/Downloads", "~/Documents", "~/Pictures", "~")
+
+
+def _expand(value: str | Path) -> Path:
+    """Expand ~ and environment variables relative to the invoking user."""
+    text = os.path.expandvars(str(value))
+    if text == "~":
+        return HOME
+    if text.startswith("~/"):
+        return HOME / text[2:]
+    return Path(text)
+
+
+# ----------------------------------------------------------------------
+# The config object
+# ----------------------------------------------------------------------
+
+# Allowed range for rescan_after_signature_updates in a config file.
+# Below 7 is a full pass of a big machine every few days; above 31 leaves
+# clean files unchecked for over a month. 0 (off) is always allowed.
+SIGNATURE_RESCAN_MIN = 7
+SIGNATURE_RESCAN_MAX = 31
+
+
+@dataclass(frozen=True)
+class Config:
+    db_url: str = f"sqlite:///{DEFAULT_DATA_DIR / 'system.db'}"
+    log_file: Path = DEFAULT_DATA_DIR / "error_logs.txt"
+    clamd_socket: str = "/var/run/clamav/clamd.ctl"
+    # 0 = auto: sized from clamd's MaxThreads and CPU count at startup.
+    max_workers: int = 0
+    rescan_after_days: int = 90
+    # Rescan a clean file once the signature database has moved this many
+    # versions past the one it was last scanned under. Usually about one
+    # version per day, so this is roughly "days". A config file may set
+    # SIGNATURE_RESCAN_MIN..SIGNATURE_RESCAN_MAX (clamped, with a warning),
+    # or 0 to turn it off.
+    rescan_after_signature_updates: int = 7
+    # Seconds before the infected-files desktop alert closes itself, so it
+    # doesn't sit over a game until dismissed. 0 = stays until dismissed.
+    infected_alert_seconds: int = 60
+    # Error logs are one file per run under <data_dir>/logs/. Delete runs
+    # older than this many days (0 = never)...
+    log_keep_days: int = 90
+    # ...and, if the folder is still bigger than this many MB, the oldest
+    # first (0 = no size limit). The size limit wins when the two disagree.
+    log_max_total_mb: int = 2048
+    # Apply infected_alert_seconds only while a Steam game is running;
+    # otherwise the alert stays until dismissed.
+    infected_alert_only_while_gaming: bool = True
+    # Warn (not block) if the loaded virus-signature database is older
+    # than this. Usually means freshclam has silently stopped running.
+    signature_max_age_days: int = 3
+    snapshot_roots: tuple[str, ...] = ()
+    # Path prefixes to skip entirely (high-churn temp/cache trees).
+    excludes: tuple[str, ...] = ()
+    scan_targets: tuple[Path, ...] = tuple(_expand(t) for t in _DEFAULT_TARGETS)
+
+    # User-supplied additions to secrets.py's pattern lists and
+    # explanations.py's curated lookup tables, from the [custom_secrets],
+    # [custom_threats] and [custom_pacman_reasons] config sections.
+    # Raw dicts, straight from TOML -- secrets.load_custom() and
+    # explanations.load_custom() validate and apply them (additive-only).
+    custom_secrets: dict = field(default_factory=dict)
+    custom_threats: dict = field(default_factory=dict)
+    custom_pacman_reasons: dict = field(default_factory=dict)
+
+    # Where this config came from, for the startup banner. Not a setting.
+    source: str = field(default="built-in defaults", compare=False)
+
+    # -- loading ------------------------------------------------------
+
+    @classmethod
+    def load(cls, path: str | Path | None = None) -> "Config":
+        """Load config: explicit path > $ENSIGN_CONFIG > default location.
+
+        An explicitly requested file that doesn't exist is an error; the
+        default location merely falling back to defaults is not.
+        """
+        explicit = path or os.environ.get("ENSIGN_CONFIG")
+        cfg_path = Path(explicit) if explicit else DEFAULT_CONFIG_PATH
+
+        if not cfg_path.is_file():
+            if explicit:
+                raise FileNotFoundError(f"Config file not found: {cfg_path}")
+            return cls()
+
+        with open(cfg_path, "rb") as f:
+            data = tomllib.load(f)
+
+        # Per-machine overrides: [hosts.<hostname>] beats top level.
+        host_overrides = data.pop("hosts", {}).get(HOSTNAME, {})
+        merged = {**data, **host_overrides}
+        return cls._from_dict(merged, source=str(cfg_path))
+
+    @classmethod
+    def _from_dict(cls, raw: dict, source: str) -> "Config":
+        known = {
+            "data_dir", "clamd_socket", "max_workers",
+            "rescan_after_days", "rescan_after_signature_updates",
+            "infected_alert_seconds", "infected_alert_only_while_gaming",
+            "log_keep_days", "log_max_total_mb",
+            "scan_targets", "snapshot_roots",
+            "excludes", "signature_max_age_days",
+            "custom_secrets", "custom_threats", "custom_pacman_reasons",
+        }
+        for key in raw.keys() - known:
+            print(f"[ensign] Warning: unknown config key {key!r} ignored")
+
+        data_dir = _expand(raw.get("data_dir", DEFAULT_DATA_DIR))
+        kwargs: dict = {
+            "db_url": f"sqlite:///{data_dir / 'system.db'}",
+            "log_file": data_dir / "error_logs.txt",
+            "source": source,
+        }
+        for key in ("clamd_socket", "max_workers", "rescan_after_days",
+                    "rescan_after_signature_updates", "infected_alert_seconds",
+                    "infected_alert_only_while_gaming", "log_keep_days",
+                    "log_max_total_mb", "signature_max_age_days"):
+            if key in raw:
+                kwargs[key] = raw[key]
+        if "scan_targets" in raw:
+            kwargs["scan_targets"] = tuple(_expand(t) for t in raw["scan_targets"])
+        if "snapshot_roots" in raw:
+            kwargs["snapshot_roots"] = tuple(str(_expand(t)) for t in raw["snapshot_roots"])
+        if "excludes" in raw:
+            kwargs["excludes"] = tuple(str(_expand(t)).rstrip("/") for t in raw["excludes"])
+        for key in ("custom_secrets", "custom_threats", "custom_pacman_reasons"):
+            if key in raw:
+                kwargs[key] = raw[key]
+        n = kwargs.get("rescan_after_signature_updates")
+        if isinstance(n, int) and n != 0:
+            clamped = min(max(n, SIGNATURE_RESCAN_MIN), SIGNATURE_RESCAN_MAX)
+            if clamped != n:
+                print(f"[ensign] Warning: rescan_after_signature_updates = {n} is outside "
+                      f"{SIGNATURE_RESCAN_MIN}-{SIGNATURE_RESCAN_MAX}; using {clamped}")
+                kwargs["rescan_after_signature_updates"] = clamped
+        return cls(**kwargs)
+
+    @property
+    def data_dir(self) -> Path:
+        return self.log_file.parent
+
+    @property
+    def log_dir(self) -> Path:
+        return self.data_dir / "logs"
+
+
+# ----------------------------------------------------------------------
+# First-run template
+# ----------------------------------------------------------------------
+# EXAMPLE_CONFIG must stay identical to config.example.toml at the repo
+# root (config_test.py checks this). Edit the .toml, then copy it here.
+
+EXAMPLE_CONFIG = """\
+# Ensign configuration.
+# Paths may use "~" (the invoking user's home, sudo-safe) and $VARS.
+# Anything set under [hosts.<hostname>] overrides the values above it
+# on that machine only — so this one file can be synced everywhere.
+
+# Where the database and error log live.
+# data_dir = "~/.local/share/ensign"
+
+# Worker threads. 0 = auto (sized from clamd's MaxThreads and CPU count).
+max_workers = 0
+rescan_after_days = 90
+
+# Rescan an unchanged, previously-clean file once the virus-signature
+# database has moved this many versions past the one it was last scanned
+# under. The database moves about once a day, so this is roughly "days":
+# 7 = every file is re-checked about weekly, 31 = about monthly. Allowed
+# range 7-31 (anything else is clamped, with a warning); 0 turns it off.
+# Each rescan is a full clamd pass over everything that is out of date,
+# which on a large machine (millions of files) is a long one.
+rescan_after_signature_updates = 7
+
+# Seconds before the "infected files" desktop alert closes itself, so it
+# doesn't sit on top of a game until you dismiss it. Longer than a normal
+# alert on purpose. 0 = stays until you dismiss it. Other alerts are not
+# affected.
+infected_alert_seconds = 60
+
+# true = for a scan you start yourself in a terminal, only auto-close that
+# alert while a Steam game is running, so it stays on screen until you come
+# back to it. false = always auto-close. (Steam open but idle does not count
+# as gaming.) Runs with no terminal (a service or cron job) always auto-close,
+# and each new infected alert replaces the previous one instead of stacking.
+infected_alert_only_while_gaming = true
+
+# Error logs: one file per run in <data_dir>/logs/, created only when a run
+# has errors. Runs older than log_keep_days are deleted; if the folder is
+# still over log_max_total_mb, the oldest go first (so the size limit wins).
+# 0 turns either rule off. Within a run, an error that repeats is logged in
+# full 20 times, then only counted, with a total at the end of the run.
+log_keep_days = 90
+log_max_total_mb = 2048
+
+# Warn if the virus-signature database is older than this many days
+# (usually means freshclam has silently stopped running). 0 disables.
+signature_max_age_days = 3
+clamd_socket = "/var/run/clamav/clamd.ctl"
+
+scan_targets = [
+    "~/Downloads",
+    "~/Documents",
+    "~/Pictures",
+    "~",
+]
+
+# Directory trees whose contents never change in place (e.g. proton
+# prefix snapshots). Unchanged subtrees under these are skipped by mtime.
+snapshot_roots = []
+
+# Trees to skip entirely. High-churn temp/cache directories mostly
+# produce "file vanished mid-scan" errors and no security value.
+# If you use snapper (or another btrfs snapshot tool) on a subvolume
+# under your home directory, its .snapshots dir holds full copies of
+# your whole home tree per snapshot -- left un-excluded, Ensign will
+# walk every file once per snapshot, and the count balloons with each
+# new snapshot snapper takes.
+excludes = [
+    "~/.cache",
+    "~/.local/share/Trash",
+    "~/.snapshots",
+]
+
+# --- Per-machine overrides (section name = `hostname` output) ---------
+#
+# [hosts.gaming-rig]
+# max_workers = 8          # explicit override beats auto
+# scan_targets = ["~/Downloads", "~/.local/share/Steam", "~"]
+# snapshot_roots = [
+#     "~/.local/share/Steam/steamapps/compatdata/<app_id>/pfx/dosdevices/z:/snapshots",
+# ]
+#
+# [hosts.old-laptop]
+# max_workers = 2
+
+# --- Custom secrets-path patterns (ensign_scan/secrets.py) ------------------
+# Additive only: these are ADDED to the built-in HIGH/MEDIUM pattern
+# lists, never replace or override a built-in entry. See secrets.py's
+# module docstring for what HIGH vs MEDIUM means.
+#
+# [custom_secrets]
+# high_dirs = ["myvault"]                        # whole path component
+# high_dir_paths = ["myapp/keys"]                # multi-segment substring
+# high_filenames = ["my_custom_key"]              # exact filename, any dir
+# high_extensions = [".mysecret"]
+# high_scoped_filenames = [["myapp", "config"]]   # [required parent substring, filename]
+# high_prefixes = [["mywallet_", "wallets"]]     # [prefix, required parent substring]
+# medium_prefixes = [["myprefix_", "somedir"]]    # [prefix, required parent substring or ""]
+# medium_extensions = [[".maybesecret", ""]]      # [extension, required parent substring or ""]
+
+# --- Custom explanations (ensign_scan/explanations.py) -----------------------
+# Additive only, same as above -- a name/reason that's already built in
+# is left alone, not overridden.
+#
+# [custom_threats."Some.New.ThreatName"]
+# description = "What this signature generally means."
+# false_positive_note = "Optional: when it's commonly a false positive."
+#
+# [custom_pacman_reasons]
+# "Some new mismatch type" = "What this pacman -Qkk reason means."
+"""
+
+
+def ensure_default_config() -> None:
+    """Write the commented template on first run so users have something
+    to edit instead of reading source code to learn the options."""
+    if DEFAULT_CONFIG_PATH.exists():
+        return
+    DEFAULT_CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    DEFAULT_CONFIG_PATH.write_text(EXAMPLE_CONFIG)
+    print(f"[ensign] Wrote starter config to {DEFAULT_CONFIG_PATH}")