macverify 1.0.0__py3-none-any.whl

macverify/__init__.py

@@ -0,0 +1,39 @@
+import os
+import re
+
+DISTRIBUTION = "macverify"
+
+UNKNOWN_VERSION = "0+unknown"
+
+
+def _installed_version():
+    try:
+        from importlib.metadata import PackageNotFoundError, version
+    except ImportError:
+        return None
+    try:
+        return version(DISTRIBUTION)
+    except PackageNotFoundError:
+        return None
+    except Exception:
+        return None
+
+
+def _source_version():
+    path = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "pyproject.toml")
+    try:
+        with open(path, "r", encoding="utf-8") as handle:
+            for line in handle:
+                match = re.match(r'^\s*version\s*=\s*["\']([^"\']+)["\']\s*$', line)
+                if match:
+                    return match.group(1)
+    except (OSError, ValueError):
+        return None
+    return None
+
+
+def _resolve_version():
+    return _installed_version() or _source_version() or UNKNOWN_VERSION
+
+
+__version__ = _resolve_version()

macverify/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

macverify/aicommon.py

@@ -0,0 +1,112 @@
+import os
+import re
+
+from . import fsutil
+
+STOPWORDS = {
+    "the", "a", "an", "and", "or", "for", "with", "when", "use", "using", "used", "this", "that", "to", "of", "in",
+    "on", "by", "is", "are", "be", "it", "its", "as", "at", "from", "into", "you", "your", "should", "can", "will",
+    "any", "all", "not", "but", "if", "then", "than", "also", "via", "per", "up", "out", "over", "before", "after",
+    "skill", "skills", "agent", "agents", "command", "commands", "claude", "code", "user", "users", "need", "needs",
+    "have", "has", "was", "were", "there", "their", "them", "they", "what", "which", "who", "how", "why", "more",
+}
+
+NOT_APPLICABLE = "n/a"
+
+MAX_ANCESTOR_DEPTH = 12
+
+
+def tokens(text):
+    words = re.findall(r"[a-z][a-z0-9_-]{2,}", (text or "").lower())
+    return {word for word in words if word not in STOPWORDS}
+
+
+def similarity(left, right):
+    if not left or not right:
+        return 0.0, []
+    shared = left & right
+    union = left | right
+    if not union:
+        return 0.0, []
+    return round(len(shared) / float(len(union)), 3), sorted(shared)
+
+
+def cost(always_bytes, on_demand_bytes):
+    return {
+        "always_loaded_bytes": always_bytes,
+        "always_loaded_tokens_estimate": always_bytes // 4,
+        "on_demand_bytes": on_demand_bytes,
+        "on_demand_tokens_estimate": on_demand_bytes // 4,
+    }
+
+
+def no_cost(reason):
+    return {
+        "always_loaded_bytes": None,
+        "always_loaded_tokens_estimate": NOT_APPLICABLE,
+        "on_demand_bytes": None,
+        "on_demand_tokens_estimate": NOT_APPLICABLE,
+        "measurement_note": reason,
+    }
+
+
+def headings(body, limit=40):
+    outline = []
+    for line in (body or "").splitlines():
+        match = re.match(r"^(#{1,6})\s+(.+?)\s*#*$", line)
+        if match:
+            outline.append({"level": len(match.group(1)), "text": match.group(2)[:120]})
+        if len(outline) >= limit:
+            break
+    return outline
+
+
+def ancestors(start, home, include_home=True):
+    chain = []
+    current = os.path.abspath(start)
+    while True:
+        chain.append(current)
+        parent = os.path.dirname(current)
+        if parent == current or len(chain) >= MAX_ANCESTOR_DEPTH:
+            break
+        if current == home:
+            break
+        current = parent
+    if include_home and home not in chain and fsutil.exists(home):
+        chain.append(home)
+    return chain
+
+
+def project_roots(ctx):
+    roots = []
+    for root in [ctx.cwd] + list(ctx.projects):
+        absolute = os.path.abspath(os.path.expanduser(root))
+        if absolute not in roots:
+            roots.append(absolute)
+    return roots
+
+
+def search_roots(ctx):
+    home = fsutil.home()
+    seen = []
+    for root in project_roots(ctx):
+        for candidate in ancestors(root, home):
+            if candidate not in seen:
+                seen.append(candidate)
+    return seen
+
+
+def quote_lines(text, terms, limit=2, width=160):
+    if not text or not terms:
+        return []
+    wanted = set(terms)
+    picked = []
+    for line in text.splitlines():
+        stripped = line.strip().lstrip("#").strip()
+        if len(stripped) < 20:
+            continue
+        if tokens(stripped) & wanted:
+            picked.append(stripped[:width])
+        if len(picked) >= limit:
+            break
+    return picked

macverify/cli.py

@@ -0,0 +1,231 @@
+import argparse
+import datetime
+import json
+import os
+import sys
+
+from . import __version__, compat, findings as findings_mod, quickfix, registry, report_html, report_md, runner, scope as scope_mod, sysinfo
+from .context import Context
+
+REPORT_DIR = os.path.join(os.path.expanduser("~"), ".macverify", "reports")
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="macverify",
+        description="Read-only inventory of a macOS user space and its AI assistant configuration. Nothing is modified, elevated, or sent over the network.",
+    )
+    parser.add_argument("--version", action="version", version="macverify %s" % __version__, help="print the installed version and exit")
+    parser.add_argument("--only", action="append", metavar="DOMAIN", help="run only this domain (repeatable)")
+    parser.add_argument("--skip", action="append", metavar="DOMAIN", help="skip this domain (repeatable)")
+    parser.add_argument("--json-only", action="store_true", help="write the JSON dataset only")
+    parser.add_argument("--html-only", action="store_true", help="write the HTML report only")
+    parser.add_argument("--out", metavar="DIR", default=REPORT_DIR, help="output directory (default: ~/.macverify/reports)")
+    parser.add_argument("--timeout", type=float, default=8.0, metavar="S", help="per-command timeout in seconds (default: 8)")
+    parser.add_argument("--lang", choices=("en", "es"), default="en", help="report label language (default: en)")
+    parser.add_argument("--project", action="append", metavar="PATH", help="extra project root to inspect for AI assistant config (repeatable)")
+    parser.add_argument("--verbose", action="store_true", help="print per-domain progress to stderr")
+    parser.add_argument("--list-domains", action="store_true", help="list domain names and exit")
+    parser.add_argument("--quick-fixes", action="store_true", help="print the quick-fix plan to stdout as well as writing the reports")
+    parser.add_argument("--check", action="store_true", help="report what this machine can be audited for, then exit without collecting")
+    return parser
+
+
+def _log(enabled, message):
+    if enabled:
+        sys.stderr.write("[macverify] %s\n" % message)
+        sys.stderr.flush()
+
+
+def _collect_findings(results):
+    collected = []
+    for domain in sorted(results):
+        for item in results[domain].get("findings") or []:
+            if isinstance(item, dict) and item.get("id"):
+                collected.append(item)
+    return findings_mod.sort_findings(collected)
+
+
+def main(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.list_domains:
+        for domain in registry.DOMAINS:
+            sys.stdout.write("%s\n" % domain)
+        return 0
+
+    host = compat.preflight()
+    if args.check:
+        _print_check(host)
+        return 0 if host["supported"] else 1
+    if not host["supported"]:
+        sys.stderr.write("macverify cannot run here: %s\n" % host["reason"])
+        return 1
+    for warning in host["warnings"]:
+        _log(True, warning)
+
+    domains, unknown = registry.resolve(args.only, args.skip)
+    for name in unknown:
+        _log(True, "unknown domain ignored: %s" % name)
+    if not domains:
+        _log(True, "no domains selected")
+        return 0
+
+    projects = [os.path.abspath(os.path.expanduser(path)) for path in (args.project or [])]
+    ctx = Context(timeout=max(1.0, args.timeout), projects=projects, verbose=args.verbose, lang=args.lang)
+
+    started = datetime.datetime.now(datetime.timezone.utc)
+    _log(args.verbose, "running %d domains with a %.0fs per-command timeout" % (len(domains), ctx.timeout))
+    results = runner.run_all(domains, ctx)
+    elapsed = (datetime.datetime.now(datetime.timezone.utc) - started).total_seconds()
+
+    for domain in domains:
+        _log(args.verbose, "%-12s %s" % (domain, results[domain].get("status")))
+
+    all_findings = _collect_findings(results)
+    tally = findings_mod.counts(all_findings)
+    plan = quickfix.build(all_findings)
+    stamp = started.strftime("%Y%m%dT%H%M%SZ")
+
+    dataset = {
+        "schema_version": 1,
+        "tool": {"name": "macverify", "version": __version__, "mode": "read-only"},
+        "generated_at": started.strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "system": sysinfo.snapshot(),
+        "compatibility": host,
+        "scope": {
+            "reads": scope_mod.scope(args.lang)["does"],
+            "cannot_detect": scope_mod.scope(args.lang)["not"],
+            "recommended_scanners": scope_mod.scope(args.lang)["av_tools"],
+        },
+        "run": {
+            "domains": list(domains),
+            "per_command_timeout_seconds": ctx.timeout,
+            "language": args.lang,
+            "extra_projects": projects,
+            "statuses": {domain: results[domain].get("status") for domain in domains},
+        },
+        "summary": {
+            "finding_counts": tally,
+            "total_findings": len(all_findings),
+            "domains_ok": sorted(d for d in domains if results[d].get("status") == "ok"),
+            "domains_degraded": sorted(d for d in domains if results[d].get("status") not in ("ok",)),
+        },
+        "findings": all_findings,
+        "quick_fixes": plan,
+        "domains": {domain: results[domain] for domain in domains},
+    }
+
+    out_dir = os.path.abspath(os.path.expanduser(args.out))
+    try:
+        newly_created = not os.path.isdir(out_dir)
+        os.makedirs(out_dir, mode=0o700, exist_ok=True)
+        if newly_created or out_dir == os.path.abspath(REPORT_DIR):
+            os.chmod(out_dir, 0o700)
+        if out_dir == os.path.abspath(REPORT_DIR):
+            os.chmod(os.path.dirname(out_dir), 0o700)
+    except OSError as exc:
+        sys.stderr.write("cannot create output directory %s: %s\n" % (out_dir, exc))
+        return 0
+
+    written = []
+    if not args.html_only:
+        json_path = os.path.join(out_dir, "audit_%s.json" % stamp)
+        _write(json_path, json.dumps(dataset, indent=2, ensure_ascii=False, default=str) + "\n")
+        written.append(json_path)
+
+    if not args.json_only:
+        html_path = os.path.join(out_dir, "audit_%s.html" % stamp)
+        _write(html_path, report_html.render(dataset, args.lang))
+        written.append(html_path)
+
+        md_path = os.path.join(out_dir, "remediation.md")
+        _write(md_path, report_md.render(dataset, args.lang))
+        written.append(md_path)
+
+    assistants = {name: results[name] for name in registry.AI_ASSISTANT_DOMAINS if name in results}
+    if assistants and not args.html_only:
+        assistant_path = os.path.join(out_dir, "ai_assistant_findings.json")
+        payload = {
+            "generated_at": dataset["generated_at"],
+            "tool": dataset["tool"],
+            "domains": assistants,
+            "statuses": {name: assistants[name].get("status") for name in sorted(assistants)},
+            "findings": [item for item in all_findings if item.get("domain") in registry.AI_ASSISTANT_DOMAINS],
+        }
+        _write(assistant_path, json.dumps(payload, indent=2, ensure_ascii=False, default=str) + "\n")
+        written.append(assistant_path)
+
+    if args.quick_fixes:
+        _print_quick_fixes(plan)
+
+    sys.stdout.write("macverify %s  read-only  offline\n" % __version__)
+    sys.stdout.write("domains: %d ok, %d degraded  findings: %d critical, %d warning, %d info  (%.1fs)\n" % (
+        len(dataset["summary"]["domains_ok"]),
+        len(dataset["summary"]["domains_degraded"]),
+        tally["critical"],
+        tally["warning"],
+        tally["info"],
+        elapsed,
+    ))
+    sys.stdout.write("quick fixes: %d commands (%d read-only, %d reversible, %d need care), %d manual steps\n" % (
+        plan["counts"]["commands"], plan["counts"]["inspect"], plan["counts"]["apply"],
+        plan["counts"]["careful"], plan["counts"]["manual_steps"]))
+    sys.stdout.write("this audit reads configuration only; it cannot detect malware. Run an anti-malware scan as well - see the Quick fixes tab.\n")
+    for path in written:
+        sys.stdout.write("wrote %s\n" % path)
+    return 0
+
+
+def _print_check(host):
+    sys.stdout.write("platform      %s\n" % host["platform"])
+    sys.stdout.write("macOS         %s (build %s)\n" % (host["macos"]["version"], host["macos"]["build"]))
+    sys.stdout.write("architecture  %s%s\n" % (
+        host["architecture"].get("native_arch"),
+        " (interpreter translated by Rosetta)" if host["architecture"].get("running_under_rosetta") else ""))
+    sys.stdout.write("python        %s\n" % host["python"]["version"])
+    sys.stdout.write("account       %s%s\n" % (
+        host["account"].get("user"),
+        " (admin)" if host["account"].get("admin") else " (standard)" if host["account"].get("admin") is False else ""))
+    sys.stdout.write("supported     %s\n" % ("yes" if host["supported"] else "no: %s" % host["reason"]))
+    for warning in host["warnings"]:
+        sys.stdout.write("warning       %s\n" % warning)
+    for note in host["capability_notes"]:
+        sys.stdout.write("%-13s %s: %s\n" % (note["expect"], note["domain"], note["detail"]))
+
+
+def _print_quick_fixes(plan):
+    headings = (
+        ("inspect", "look first, read-only"),
+        ("apply", "safe to apply, reversible"),
+        ("careful", "read before running"),
+    )
+    for tier, heading in headings:
+        items = quickfix.by_tier(plan, tier)
+        if not items:
+            continue
+        sys.stdout.write("\n# %s\n" % heading)
+        for entry in items:
+            sys.stdout.write("# %s\n" % "; ".join(entry["titles"][:2]))
+            sys.stdout.write("%s\n" % entry["command"])
+    if plan["manual_steps"]:
+        sys.stdout.write("\n# steps with no command\n")
+        for entry in plan["manual_steps"]:
+            sys.stdout.write("# %s -> %s\n" % ("; ".join(entry["titles"][:2]), entry["manual_step"]))
+    sys.stdout.write("\n")
+
+
+def _write(path, text):
+    try:
+        descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        try:
+            with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+                descriptor = None
+                handle.write(text)
+        finally:
+            if descriptor is not None:
+                os.close(descriptor)
+        os.chmod(path, 0o600)
+    except OSError as exc:
+        sys.stderr.write("cannot write %s: %s\n" % (path, exc))

macverify/collectors/ai_assistants.py

@@ -0,0 +1,208 @@
+import os
+
+from .. import aicommon
+from .. import findings as F
+from .. import fsutil
+from ..context import default_context
+
+INSTRUCTION_FILES = (
+    ("claude_code", "CLAUDE.md", "CLAUDE.md"),
+    ("openai_codex", "AGENTS.md", "AGENTS.md"),
+    ("github_copilot", os.path.join(".github", "copilot-instructions.md"), ".github/copilot-instructions.md"),
+)
+
+OVERLAP_SCORE = 0.18
+
+OVERLAP_MINIMUM_TERMS = 6
+
+STRONG_OVERLAP_SCORE = 0.4
+
+
+def _entry(tool, label, path, directory, active, active_reason):
+    text = fsutil.read_text(path) or ""
+    size = len(text.encode("utf-8"))
+    return {
+        "tool": tool,
+        "label": label,
+        "path": fsutil.tilde(path),
+        "directory": fsutil.tilde(directory),
+        "file_bytes": size,
+        "line_count": len(text.splitlines()),
+        "empty": not text.strip(),
+        "active": active,
+        "active_reason": active_reason,
+        "heading_outline": aicommon.headings(text, limit=12),
+        "context_cost": aicommon.cost(size if active else 0, 0 if active else size),
+        "_tokens": aicommon.tokens(text),
+        "_text": text,
+    }
+
+
+def collect(ctx=None):
+    ctx = default_context(ctx)
+    home = fsutil.home()
+    cwd = os.path.abspath(ctx.cwd)
+    roots = aicommon.project_roots(ctx)
+
+    entries = []
+    seen = set()
+    for root in roots:
+        for directory in aicommon.ancestors(root, home):
+            for tool, relative, label in INSTRUCTION_FILES:
+                path = os.path.join(directory, relative)
+                if path in seen or not fsutil.exists(path):
+                    continue
+                seen.add(path)
+                if directory == cwd:
+                    active, reason = True, "in the current directory"
+                elif cwd.startswith(directory.rstrip(os.sep) + os.sep):
+                    active, reason = True, "ancestor of the current directory"
+                else:
+                    active, reason = False, "belongs to %s, which is not the current directory" % fsutil.tilde(directory)
+                entries.append(_entry(tool, label, path, directory, active, reason))
+
+    if not entries:
+        return {
+            "status": "unavailable",
+            "reason": "no CLAUDE.md, AGENTS.md or .github/copilot-instructions.md found in the inspected project roots or their ancestors",
+            "inventory": {},
+            "analysis": {},
+            "findings": [],
+        }
+
+    by_directory = {}
+    for entry in entries:
+        by_directory.setdefault(entry["directory"], []).append(entry)
+
+    overlaps = []
+    for directory in sorted(by_directory):
+        group = by_directory[directory]
+        if len(group) < 2:
+            continue
+        for index in range(len(group)):
+            for other_index in range(index + 1, len(group)):
+                left = group[index]
+                right = group[other_index]
+                score, shared = aicommon.similarity(left["_tokens"], right["_tokens"])
+                union = len(left["_tokens"] | right["_tokens"])
+                overlaps.append({
+                    "directory": directory,
+                    "left": {
+                        "tool": left["tool"],
+                        "file": left["label"],
+                        "path": left["path"],
+                        "bytes": left["file_bytes"],
+                        "quoted_lines": aicommon.quote_lines(left["_text"], shared) or aicommon.quote_lines(left["_text"], left["_tokens"], limit=1),
+                    },
+                    "right": {
+                        "tool": right["tool"],
+                        "file": right["label"],
+                        "path": right["path"],
+                        "bytes": right["file_bytes"],
+                        "quoted_lines": aicommon.quote_lines(right["_text"], shared) or aicommon.quote_lines(right["_text"], right["_tokens"], limit=1),
+                    },
+                    "score": score,
+                    "shared_terms": shared[:16],
+                    "shared_term_count": len(shared),
+                    "above_reporting_threshold": score >= OVERLAP_SCORE and len(shared) >= OVERLAP_MINIMUM_TERMS,
+                    "evidence": "%d of %d combined domain terms are shared (%s vocabulary overlap)" % (
+                        len(shared), union, "{:.0%}".format(score)),
+                })
+
+    multi_tool_directories = []
+    for directory in sorted(by_directory):
+        group = by_directory[directory]
+        tools = sorted({entry["tool"] for entry in group})
+        if len(tools) < 2:
+            continue
+        pairs = [item for item in overlaps if item["directory"] == directory]
+        multi_tool_directories.append({
+            "directory": directory,
+            "tools": tools,
+            "files": [{"tool": entry["tool"], "file": entry["label"], "path": entry["path"], "bytes": entry["file_bytes"], "active": entry["active"], "empty": entry["empty"]} for entry in group],
+            "total_bytes": sum(entry["file_bytes"] for entry in group),
+            "active_bytes": sum(entry["file_bytes"] for entry in group if entry["active"]),
+            "pairwise_similarity": [
+                {"files": "%s vs %s" % (item["left"]["file"], item["right"]["file"]), "score": item["score"],
+                 "shared_term_count": item["shared_term_count"], "above_reporting_threshold": item["above_reporting_threshold"]}
+                for item in sorted(pairs, key=lambda entry: -entry["score"])
+            ],
+            "highest_score": max([item["score"] for item in pairs] or [0.0]),
+        })
+
+    tools_present = sorted({entry["tool"] for entry in entries})
+    active_entries = [entry for entry in entries if entry["active"]]
+    per_tool = {}
+    for entry in entries:
+        bucket = per_tool.setdefault(entry["tool"], {"files": 0, "active": 0, "bytes": 0, "active_bytes": 0})
+        bucket["files"] += 1
+        bucket["bytes"] += entry["file_bytes"]
+        if entry["active"]:
+            bucket["active"] += 1
+            bucket["active_bytes"] += entry["file_bytes"]
+    for bucket in per_tool.values():
+        bucket["active_tokens_estimate"] = bucket["active_bytes"] // 4
+
+    public = []
+    for entry in entries:
+        clean = {key: value for key, value in entry.items() if not key.startswith("_")}
+        public.append(clean)
+
+    inventory = {
+        "tools_with_instruction_files": tools_present,
+        "instruction_files": sorted(public, key=lambda item: (item["directory"], item["label"])),
+        "directories_with_more_than_one_tool": multi_tool_directories,
+        "per_tool": dict(sorted(per_tool.items())),
+        "project_roots_inspected": [fsutil.tilde(root) for root in roots],
+    }
+
+    analysis = {
+        "instruction_file_count": len(entries),
+        "active_instruction_file_count": len(active_entries),
+        "combined_active_bytes": sum(entry["file_bytes"] for entry in active_entries),
+        "combined_active_tokens_estimate": sum(entry["file_bytes"] for entry in active_entries) // 4,
+        "instruction_file_overlaps": overlaps,
+        "method": "two instruction files in the same directory are compared by the Jaccard overlap of their content vocabularies after stopword removal; a finding is only raised when at least %d domain terms are shared, and every finding carries lines quoted from both files" % OVERLAP_MINIMUM_TERMS,
+    }
+
+    findings = []
+    for entry in multi_tool_directories:
+        pairs = [item for item in overlaps if item["directory"] == entry["directory"]]
+        top = max(pairs, key=lambda item: item["score"]) if pairs else None
+        crossing = [item for item in pairs if item["above_reporting_threshold"]]
+        basis = []
+        if top:
+            for side in ("left", "right"):
+                quotes = top[side]["quoted_lines"]
+                if quotes:
+                    basis.append('%s says "%s"' % (top[side]["file"], quotes[0]))
+        scores = "; ".join("%s %s" % (item["files"], "{:.0%}".format(item["score"])) for item in entry["pairwise_similarity"])
+        if crossing:
+            severity = "warning" if entry["highest_score"] >= STRONG_OVERLAP_SCORE else "info"
+            matters = "The same conventions maintained in two instruction files are loaded separately by each assistant and drift apart, so the two tools end up working to different versions of the same rule."
+            action = "Keep the shared rules in one file and have the others point at it, or split them so each file states only what is specific to its assistant"
+        else:
+            severity = "info"
+            matters = "Separate instruction files per assistant are only a problem when they drift; here they describe different things, so the cost is maintaining several files rather than contradicting guidance."
+            action = "Decide which file is authoritative for shared conventions, and have the others reference it rather than restate it"
+        findings.append(F.finding(
+            "ai_assistants",
+            severity,
+            "%s carries instruction files for %d assistants" % (entry["directory"], len(entry["tools"])),
+            "%s. Vocabulary overlap: %s. %s" % (
+                ", ".join("%s (%s, %s)" % (item["file"], item["tool"], fsutil.human_bytes(item["bytes"])) for item in entry["files"]),
+                scores or "not comparable",
+                " ".join(basis) if basis else "no quotable content in either file",
+            ),
+            matters,
+            action,
+            True,
+            key="multi-tool-%s" % entry["directory"],
+        ))
+
+    return {
+        "status": "ok",
+        "inventory": inventory,
+        "analysis": analysis,
+        "findings": findings,
+    }