auditwalk 0.1.0__tar.gz

auditwalk-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: auditwalk
+Version: 0.1.0
+Summary: AuditWalk
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# AuditWalk
+
+Local-first security + audit toolkit to capture evidence from the browser, queue it for review, and run lightweight integrity scans without leaving your machine.
+
+## Build Planning
+- Master MVP checklist: `docs/MVP_BUILD_DOCUMENTATION.md`
+- Execution roadmap: `docs/ROADMAP.md`
+- Near-term task list: `TODO.md`
+- Module ownership map: `docs/architecture/module_ownership.md`
+
+## Quick Start (Developer Setup)
+
+Clone the repository and run the initial setup:
+
+```bash
+make install-dev
+make hooks
+make repo-steward-check
+```
+
+This will:
+- Install development dependencies into the local virtual environment
+- Install the repository pre-commit hook
+- Verify repository stewardship checks pass
+
+## Developer setup
+
+Install the local git pre-commit hook:
+
+```bash
+make hooks
+```
+
+Check whether it is installed:
+
+```bash
+make hooks-status
+```
+
+## MVP Scope
+- Bookmarklet that POSTs the active tab (URL + title + timestamp) to a localhost ingest endpoint.
+- Loopback-only ingest server (`scripts/run_ingest.py`) that validates payloads and appends them to `~/.auditwalk/inbox.jsonl`.
+- Inbox utilities + CLI commands (`scripts/auditwalk_cli.py`) for listing, processing, and manually adding queue entries.
+- Hardened file-system scanner (`scanner.py`) with optional hashing, suspicious-extension detection, and JSON export to feed future analysis steps.
+- Documentation covering install, security notes, and usage so Antoine can run the MVP end-to-end.
+
+## Install
+```bash
+# Clone + enter repo
+cd ~/DevEnv
+# (repo already exists locally, update if needed)
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt  # if/when we add one; for now: pip install rich tqdm
+```
+
+## Usage
+### 1. Run the ingest server
+```bash
+source venv/bin/activate
+python3 scripts/run_ingest.py --port 8841 --token YOUR_SHARED_TOKEN
+```
+Options:
+- `--host` (default `127.0.0.1`)
+- `--port` (default `8841`)
+- `--inbox` (default `~/.auditwalk/inbox.jsonl`)
+- `--token` (optional shared secret; bookmarklet must send `X-AuditWalk-Token` header)
+
+### 2. Install the bookmarklet
+Create a new browser bookmark with the URL field set to:
+```
+javascript:(()=>{const data={url:location.href,title:document.title,timestamp:Date.now()/1000,source:'bookmarklet'};fetch('http://127.0.0.1:8841/share',{method:'POST',headers:{'Content-Type':'application/json','X-AuditWalk-Token':'TOKEN_HERE'},body:JSON.stringify(data)}).then(()=>console.log('Sent to AuditWalk')).catch(err=>alert('AuditWalk share failed: '+err));})();
+```
+Update `TOKEN_HERE` if you launched the server with `--token`.
+
+### 3. Manage the inbox
+```bash
+python3 scripts/auditwalk_cli.py inbox-list --limit 10
+python3 scripts/auditwalk_cli.py inbox-process --clear
+python3 scripts/auditwalk_cli.py inbox-add https://example.com --title "Manual"
+```
+- `inbox-list` – prints recent captures.
+- `inbox-process` – dumps entries (optionally `--clear`).
+- `inbox-add` – helper for manual testing without the bookmarklet.
+
+### 4. Run the scanner
+```bash
+python3 scanner.py --path /home/adenmediagroup --recent-hours 24 --json-report outputs/scan.json
+```
+Flags:
+- `--no-hash` to skip SHA-256 (faster, no dedupe)
+- `--suspicious-exts ".exe,.dll"` to customize detection list
+- `--json-report` to capture structured results for later diffing
+
+## Outputs
+- **Inbox file:** `~/.auditwalk/inbox.jsonl` (one JSON object per line). Use the CLI to view/process entries.
+- **Scanner report:** Rich tables in the console + optional JSON file containing every record, suspicious hits, and recent-change counts.
+- **Docs:** `docs/inbox_workflow.md` for the share workflow, plus this README for quick start.
+
+## Security Notes
+- Ingest server binds to `127.0.0.1` only. Keep it behind a shared token to avoid drive-by localhost POSTs.
+- Bookmarklet may require allowing mixed content on strict HTTPS pages.
+- Inbox file inherits your home permissions; ensure `~/.auditwalk` is not world-readable.
+- Scanner skip lists prevent re-hashing this repo and common churn directories; adjust as needed per environment.

auditwalk-0.1.0/README.md

@@ -0,0 +1,104 @@
+# AuditWalk
+
+Local-first security + audit toolkit to capture evidence from the browser, queue it for review, and run lightweight integrity scans without leaving your machine.
+
+## Build Planning
+- Master MVP checklist: `docs/MVP_BUILD_DOCUMENTATION.md`
+- Execution roadmap: `docs/ROADMAP.md`
+- Near-term task list: `TODO.md`
+- Module ownership map: `docs/architecture/module_ownership.md`
+
+## Quick Start (Developer Setup)
+
+Clone the repository and run the initial setup:
+
+```bash
+make install-dev
+make hooks
+make repo-steward-check
+```
+
+This will:
+- Install development dependencies into the local virtual environment
+- Install the repository pre-commit hook
+- Verify repository stewardship checks pass
+
+## Developer setup
+
+Install the local git pre-commit hook:
+
+```bash
+make hooks
+```
+
+Check whether it is installed:
+
+```bash
+make hooks-status
+```
+
+## MVP Scope
+- Bookmarklet that POSTs the active tab (URL + title + timestamp) to a localhost ingest endpoint.
+- Loopback-only ingest server (`scripts/run_ingest.py`) that validates payloads and appends them to `~/.auditwalk/inbox.jsonl`.
+- Inbox utilities + CLI commands (`scripts/auditwalk_cli.py`) for listing, processing, and manually adding queue entries.
+- Hardened file-system scanner (`scanner.py`) with optional hashing, suspicious-extension detection, and JSON export to feed future analysis steps.
+- Documentation covering install, security notes, and usage so Antoine can run the MVP end-to-end.
+
+## Install
+```bash
+# Clone + enter repo
+cd ~/DevEnv
+# (repo already exists locally, update if needed)
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt  # if/when we add one; for now: pip install rich tqdm
+```
+
+## Usage
+### 1. Run the ingest server
+```bash
+source venv/bin/activate
+python3 scripts/run_ingest.py --port 8841 --token YOUR_SHARED_TOKEN
+```
+Options:
+- `--host` (default `127.0.0.1`)
+- `--port` (default `8841`)
+- `--inbox` (default `~/.auditwalk/inbox.jsonl`)
+- `--token` (optional shared secret; bookmarklet must send `X-AuditWalk-Token` header)
+
+### 2. Install the bookmarklet
+Create a new browser bookmark with the URL field set to:
+```
+javascript:(()=>{const data={url:location.href,title:document.title,timestamp:Date.now()/1000,source:'bookmarklet'};fetch('http://127.0.0.1:8841/share',{method:'POST',headers:{'Content-Type':'application/json','X-AuditWalk-Token':'TOKEN_HERE'},body:JSON.stringify(data)}).then(()=>console.log('Sent to AuditWalk')).catch(err=>alert('AuditWalk share failed: '+err));})();
+```
+Update `TOKEN_HERE` if you launched the server with `--token`.
+
+### 3. Manage the inbox
+```bash
+python3 scripts/auditwalk_cli.py inbox-list --limit 10
+python3 scripts/auditwalk_cli.py inbox-process --clear
+python3 scripts/auditwalk_cli.py inbox-add https://example.com --title "Manual"
+```
+- `inbox-list` – prints recent captures.
+- `inbox-process` – dumps entries (optionally `--clear`).
+- `inbox-add` – helper for manual testing without the bookmarklet.
+
+### 4. Run the scanner
+```bash
+python3 scanner.py --path /home/adenmediagroup --recent-hours 24 --json-report outputs/scan.json
+```
+Flags:
+- `--no-hash` to skip SHA-256 (faster, no dedupe)
+- `--suspicious-exts ".exe,.dll"` to customize detection list
+- `--json-report` to capture structured results for later diffing
+
+## Outputs
+- **Inbox file:** `~/.auditwalk/inbox.jsonl` (one JSON object per line). Use the CLI to view/process entries.
+- **Scanner report:** Rich tables in the console + optional JSON file containing every record, suspicious hits, and recent-change counts.
+- **Docs:** `docs/inbox_workflow.md` for the share workflow, plus this README for quick start.
+
+## Security Notes
+- Ingest server binds to `127.0.0.1` only. Keep it behind a shared token to avoid drive-by localhost POSTs.
+- Bookmarklet may require allowing mixed content on strict HTTPS pages.
+- Inbox file inherits your home permissions; ensure `~/.auditwalk` is not world-readable.
+- Scanner skip lists prevent re-hashing this repo and common churn directories; adjust as needed per environment.

auditwalk-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "auditwalk"
+version = "0.1.0"
+description = "AuditWalk"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = []
+
+[project.scripts]
+auditwalk = "auditwalk.cli.main:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

auditwalk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

auditwalk-0.1.0/src/auditwalk/__init__.py

@@ -0,0 +1,23 @@
+"""AuditWalk local-first utilities."""
+
+from . import reason_codes  # compatibility shim
+from . import risk  # canonical risk package
+from .inbox import (
+    INBOX_PATH,
+    InboxItem,
+    append_item,
+    ensure_inbox,
+    iter_inbox,
+    load_inbox,
+)
+
+__all__ = [
+    "INBOX_PATH",
+    "InboxItem",
+    "append_item",
+    "ensure_inbox",
+    "iter_inbox",
+    "load_inbox",
+    "reason_codes",
+    "risk",
+]

auditwalk-0.1.0/src/auditwalk/__main__.py

@@ -0,0 +1,8 @@
+"""Module entrypoint: python -m auditwalk"""
+
+from __future__ import annotations
+
+from auditwalk.cli.main import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

auditwalk-0.1.0/src/auditwalk/cli/__init__.py

@@ -0,0 +1 @@
+"""AuditWalk CLI package."""

auditwalk-0.1.0/src/auditwalk/cli/adapters/__init__.py

@@ -0,0 +1 @@
+"""CLI adapter implementations."""

auditwalk-0.1.0/src/auditwalk/cli/adapters/argparse_app.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import argparse
+from typing import Any, Dict, Tuple
+
+from auditwalk.cli.registry import ArgSpec, CommandRegistry, OptSpec
+
+
+def _dest_from_flags(flags: Tuple[str, ...]) -> str:
+    long_flags = [f for f in flags if f.startswith("--")]
+    base = (long_flags[0] if long_flags else flags[0]).lstrip("-")
+    return base.replace("-", "_")
+
+
+def _add_option(parser: argparse.ArgumentParser, opt: OptSpec) -> None:
+    kwargs: Dict[str, Any] = {"help": opt.help, "dest": _dest_from_flags(opt.flags)}
+    if opt.takes_value:
+        kwargs["default"] = opt.default
+        if opt.choices:
+            kwargs["choices"] = list(opt.choices)
+        parser.add_argument(*opt.flags, **kwargs)
+    else:
+        parser.add_argument(*opt.flags, action="store_true", **kwargs)
+
+
+def _add_positional(parser: argparse.ArgumentParser, arg: ArgSpec) -> None:
+    kwargs: Dict[str, Any] = {"help": arg.help}
+    if arg.nargs:
+        kwargs["nargs"] = arg.nargs
+    elif not arg.required:
+        kwargs["nargs"] = "?"
+    parser.add_argument(arg.name, **kwargs)
+
+
+def _noun_help(registry: CommandRegistry, noun: str) -> str:
+    verbs = registry.verbs(noun)
+    preview = ", ".join(verbs[:5])
+    suffix = "..." if len(verbs) > 5 else ""
+    return f"{noun}: {preview}{suffix}" if preview else noun
+
+
+def build_argparse_app(registry: CommandRegistry) -> argparse.ArgumentParser:
+    root = argparse.ArgumentParser(
+        prog="auditwalk",
+        description="AuditWalk - system integrity scanning and change detection.",
+    )
+    root.set_defaults(_aw_is_root=True)
+
+    noun_subparsers = root.add_subparsers(dest="_aw_noun", metavar="<noun>")
+    noun_subparsers.required = False
+
+    verb_subparsers: Dict[str, argparse._SubParsersAction] = {}
+    for noun in registry.nouns():
+        noun_parser = noun_subparsers.add_parser(noun, help=_noun_help(registry, noun))
+        noun_parser.set_defaults(_aw_noun=noun)
+        vs = noun_parser.add_subparsers(dest="_aw_verb", metavar="<verb>")
+        vs.required = True
+        verb_subparsers[noun] = vs
+
+    for spec in registry.all_specs():
+        vs = verb_subparsers[spec.noun]
+        verb_parser = vs.add_parser(spec.verb, help=spec.summary, description=spec.summary)
+        verb_parser.set_defaults(_aw_noun=spec.noun, _aw_verb=spec.verb, _aw_handler=spec.handler)
+        for arg in spec.args:
+            _add_positional(verb_parser, arg)
+        for opt in spec.opts:
+            _add_option(verb_parser, opt)
+
+    return root

auditwalk-0.1.0/src/auditwalk/cli/commands_compare.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from auditwalk.compare.differ import default_diff_path, diff
+from auditwalk.core.errors import EXIT_COMPARE_FAILED, EXIT_OK, EXIT_REPORT_FAILED
+from auditwalk.core.jsonio import write_json
+from auditwalk.report.render_html import render_html
+from auditwalk.runs.run_store import RunStore
+from auditwalk.score.scoring import score
+
+
+def cmd_compare(args: Any) -> int:
+    store = RunStore(args.data_dir)
+    data_dir = Path(store.data_dir)
+    try:
+        store.apply_default_compare_retention()
+        store.prune_orphan_compares()
+    except Exception:
+        pass
+
+    try:
+        run_a_raw, run_b_raw = _resolve_compare_args(args, getattr(args, "baseline_run_id", None))
+        run_a = _resolve_baseline_alias(run_a_raw, getattr(args, "baseline_run_id", None))
+        left = store.load_run_bundle(run_a)
+        right = store.load_run_bundle(run_b_raw)
+        result = diff(
+            left,
+            right,
+            process_normalization_profile=str(getattr(args, "process_normalization_profile", "default")),
+            compare_profile=str(getattr(args, "profile", "off")),
+        )
+
+        out_path = _resolve_out_path(
+            args.out,
+            data_dir,
+            str(result.get("left_run_id")),
+            str(result.get("right_run_id")),
+        )
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        write_json(out_path, result)
+        store.sync_compare_index()
+    except Exception as exc:
+        print(f"compare failed: {exc}")
+        return EXIT_COMPARE_FAILED
+
+    if args.score:
+        try:
+            rules = Path(Path(__file__).resolve().parents[1] / "data" / "scoring_rules.yml")
+            score_obj = score(right, result, rules_path=rules)
+            store.save_score(run_b_raw, score_obj)
+            right["score"] = score_obj
+        except Exception as exc:
+            print(f"scoring failed: {exc}")
+            return EXIT_COMPARE_FAILED
+
+    if args.html:
+        try:
+            html_out = Path(args.html_out) if args.html_out else data_dir / "reports" / f"{right.get('meta', {}).get('run_id', 'run')}.html"
+            html_out.parent.mkdir(parents=True, exist_ok=True)
+            html_out.write_text(render_html(right, diff_bundle=result), encoding="utf-8")
+        except Exception as exc:
+            print(f"report failed: {exc}")
+            return EXIT_REPORT_FAILED
+
+    if args.format == "json" or args.json:
+        print(
+            json.dumps(
+                {
+                    "diff_path": str(out_path),
+                    "run_a_input": run_a_raw,
+                    "run_b_input": run_b_raw,
+                    "run_a_resolved": run_a,
+                    "diff": result,
+                },
+                ensure_ascii=True,
+            )
+        )
+    else:
+        print(f"Diff: {result.get('compare_id')}")
+        print(f"Saved: {out_path}")
+        profile = result.get("profile", {}) if isinstance(result.get("profile"), dict) else {}
+        if profile.get("name", "off") != "off":
+            print(
+                "note: compare profile applied "
+                f"({profile.get('name')}; ignored files left={profile.get('files_left_ignored', 0)} "
+                f"right={profile.get('files_right_ignored', 0)})"
+            )
+        norm = result.get("normalization", {}) if isinstance(result.get("normalization"), dict) else {}
+        left_norm = norm.get("processes_left", {}) if isinstance(norm.get("processes_left"), dict) else {}
+        right_norm = norm.get("processes_right", {}) if isinstance(norm.get("processes_right"), dict) else {}
+        if left_norm.get("applied") or right_norm.get("applied"):
+            print(
+                "note: process normalization applied "
+                f"(profile={left_norm.get('profile', right_norm.get('profile', 'default'))})"
+            )
+        for domain, details in (result.get("domains", {}) or {}).items():
+            counts = details.get("counts", {}) if isinstance(details, dict) else {}
+            print(
+                f"{domain}: added={counts.get('added', 0)} removed={counts.get('removed', 0)} modified={counts.get('modified', 0)}"
+            )
+
+    return EXIT_OK
+
+
+def _resolve_out_path(raw_out: Path | None, data_dir: Path, run_a: str, run_b: str) -> Path:
+    if raw_out is None:
+        return default_diff_path(data_dir, run_a, run_b)
+
+    out = Path(raw_out)
+    if out.exists() and out.is_dir():
+        return out / f"diff_{run_a}__{run_b}.json"
+
+    out_str = str(out)
+    if out_str.endswith("_"):
+        return Path(f"{out_str}{run_a}__{run_b}.json")
+
+    if out.suffix.lower() != ".json":
+        return Path(f"{out_str}_{run_a}__{run_b}.json")
+
+    return out
+
+
+def _resolve_baseline_alias(run_a: str, baseline_run_id: str | None) -> str:
+    if run_a != "baseline":
+        return run_a
+    if baseline_run_id:
+        return baseline_run_id
+    raise ValueError("baseline alias used but no baseline_run_id configured")
+
+
+def _resolve_compare_args(args: Any, baseline_run_id: str | None) -> tuple[str, str]:
+    run_a = getattr(args, "run_a", None)
+    run_b = getattr(args, "run_b", None)
+    use_baseline = bool(getattr(args, "use_baseline", False))
+
+    if use_baseline:
+        if not baseline_run_id:
+            raise ValueError("--use-baseline requested but baseline_run_id is not configured")
+        if run_b is None and run_a is not None:
+            return ("baseline", str(run_a))
+        if run_b is None:
+            raise ValueError("--use-baseline requires target run id/path")
+        return ("baseline", str(run_b))
+
+    if run_a is None or run_b is None:
+        raise ValueError("compare requires RUN_A RUN_B (or --use-baseline RUN_B)")
+
+    return (str(run_a), str(run_b))

auditwalk-0.1.0/src/auditwalk/cli/commands_scan.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+import json
+import webbrowser
+from pathlib import Path
+from typing import Any
+
+from auditwalk.compare.differ import default_diff_path, diff
+from auditwalk.core.errors import EXIT_COMPARE_FAILED, EXIT_OK, EXIT_REPORT_FAILED, EXIT_SCAN_FAILED
+from auditwalk.core.jsonio import write_json
+from auditwalk.report.render_html import render_html
+from auditwalk.runs.run_store import RunStore
+from auditwalk.scan.scanner import scan
+from auditwalk.score.scoring import score
+
+
+def cmd_scan(args: Any) -> int:
+    try:
+        result = scan(
+            mode=args.mode,
+            roots=args.roots,
+            exclude=args.exclude,
+            label=args.label,
+            baseline=args.baseline,
+            do_hash=args.hash,
+            max_files=args.max_files,
+            max_procs=args.max_procs,
+            timeout_seconds=args.timeout_seconds,
+            strict_files=args.strict_files,
+            data_dir=args.data_dir,
+        )
+    except Exception as exc:
+        print(f"scan failed: {exc}")
+        return EXIT_SCAN_FAILED
+
+    store = RunStore(args.data_dir)
+    data_dir = Path(store.data_dir)
+    try:
+        store.apply_default_compare_retention()
+        store.prune_orphan_compares()
+    except Exception:
+        pass
+
+    run_bundle = store.load_run_bundle(result["run_id"])
+    rules = Path(Path(__file__).resolve().parents[1] / "data" / "scoring_rules.yml")
+
+    # Always score the run (run-only context), then optionally rescore with diff context.
+    run_score = score(run_bundle, None, rules_path=rules)
+    store.save_score(result["run_id"], run_score)
+    run_bundle["score"] = run_score
+    result["score"] = run_score
+    result["top_findings"] = run_score.get("findings", [])[:3]
+
+    diff_bundle = None
+    compare_target = args.compare
+    if compare_target == "baseline":
+        compare_target = getattr(args, "baseline_run_id", None)
+        if not compare_target:
+            print("warning: compare target 'baseline' requested, but baseline_run_id is not configured; compare skipped.")
+
+    if args.compare_last:
+        refs = store.list_runs(last=2)
+        if len(refs) >= 2:
+            compare_target = refs[1].run_id
+        else:
+            baseline_target = getattr(args, "baseline_run_id", None)
+            if baseline_target:
+                compare_target = baseline_target
+                print(f"note: --compare-last fallback to configured baseline run: {baseline_target}")
+            else:
+                print("warning: --compare-last requested, but no prior run exists; compare skipped.")
+
+    if compare_target:
+        try:
+            left = store.load_run_bundle(compare_target)
+            diff_bundle = diff(left, run_bundle)
+            out_path = default_diff_path(data_dir, compare_target, result["run_id"])
+            write_json(out_path, diff_bundle)
+            store.sync_compare_index()
+
+            # Rescore run with diff context.
+            run_score = score(run_bundle, diff_bundle, rules_path=rules)
+            store.save_score(result["run_id"], run_score)
+            run_bundle["score"] = run_score
+            result["score"] = run_score
+            result["top_findings"] = run_score.get("findings", [])[:3]
+        except Exception as exc:
+            print(f"compare failed: {exc}")
+            return EXIT_COMPARE_FAILED
+
+    if args.html:
+        try:
+            html_out = Path(args.html_out) if args.html_out else data_dir / "reports" / f"{result['run_id']}.html"
+            html_out.parent.mkdir(parents=True, exist_ok=True)
+            html_out.write_text(render_html(run_bundle, diff_bundle=diff_bundle), encoding="utf-8")
+            if args.open:
+                webbrowser.open(html_out.resolve().as_uri())
+            result["html_path"] = str(html_out)
+        except Exception as exc:
+            print(f"report failed: {exc}")
+            return EXIT_REPORT_FAILED
+
+    _print_scan_summary(result)
+    _print_scan_warnings(run_bundle)
+    if args.json:
+        print(json.dumps(result, ensure_ascii=True))
+    return EXIT_OK
+
+
+def _print_scan_summary(result: dict) -> None:
+    score = result.get("score", {}) if isinstance(result.get("score"), dict) else {}
+    total = score.get("total", 0)
+    tier = score.get("tier", "Clean")
+    findings = result.get("top_findings", []) if isinstance(result.get("top_findings", []), list) else []
+
+    print("AuditWalk v0.1")
+    print(f"Mode: {str(result.get('mode', 'unknown')).upper()}")
+    print(f"Run: {result.get('run_id')}")
+    if result.get("label"):
+        print(f"Label: {result.get('label')}")
+    print()
+    print(f"Score: {total}  ({str(tier).upper()})")
+    print()
+    print("Findings:")
+    if findings:
+        for f in findings[:3]:
+            pts = f.get("points", 0)
+            rid = f.get("rule_id", "RULE")
+            msg = f.get("message", "finding")
+            print(f"  +{pts:<3} {rid:<12} {msg}")
+    else:
+        print("  (none)")
+    print()
+    print("Artifacts:")
+    print(f"  {result.get('run_path')}")
+    if result.get("html_path"):
+        print(f"  {result.get('html_path')}")
+
+
+def _print_scan_warnings(run_bundle: dict) -> None:
+    meta = run_bundle.get("meta", {}) if isinstance(run_bundle.get("meta"), dict) else {}
+    collector_status = meta.get("collector_status", {}) if isinstance(meta.get("collector_status"), dict) else {}
+    partial_collectors = [name for name, state in collector_status.items() if state in {"partial", "error"}]
+    files_data = run_bundle.get("files", {}) if isinstance(run_bundle.get("files"), dict) else {}
+    summary = files_data.get("collector_summary", {}) if isinstance(files_data.get("collector_summary"), dict) else {}
+    vanished = int(summary.get("vanished", 0)) if isinstance(summary.get("vanished"), int) else 0
+
+    if vanished > 0 and "files" not in partial_collectors:
+        print(f"Note: {vanished} files changed during scan (vanished).")
+
+    if not partial_collectors:
+        return
+    joined = ", ".join(sorted(partial_collectors))
+    print(f"Warning: partial collector results detected: {joined}")