mod-audit 0.1.0__py3-none-any.whl

mod_audit/__init__.py

@@ -0,0 +1,20 @@
+"""mod-audit: static supply-chain auditor for Claude Code Mods.
+
+Local, offline, stdlib-only. Scans lifecycle hooks, TypeScript/JavaScript
+source, env/API-key exfiltration patterns, and permissions manifests;
+snapshots a trusted state and diffs installed mods against it to catch
+trojanized updates.
+"""
+
+__version__ = "0.1.0"
+
+from .rules import Finding, scan_mod, scan_ts_source, scan_hook_commands, scan_permissions
+
+__all__ = [
+    "__version__",
+    "Finding",
+    "scan_mod",
+    "scan_ts_source",
+    "scan_hook_commands",
+    "scan_permissions",
+]

mod_audit/cli.py

@@ -0,0 +1,148 @@
+"""mod-audit CLI: scan, snapshot, diff for Claude Code Mods."""
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import json
+import os
+import sys
+
+from . import __version__
+from .rules import (
+    SEVERITIES,
+    build_snapshot,
+    diff_against_snapshot,
+    scan_mod,
+    severity_at_least,
+)
+
+
+def _format_text(findings) -> str:
+    if not findings:
+        return "mod-audit: no findings. Mod looks clean.\n"
+    lines = []
+    for f in findings:
+        loc = f"{f.file}:{f.line}" if f.line else f.file
+        lines.append(f"[{f.severity.upper():8}] {f.rule_id}  {loc}")
+        lines.append(f"           {f.message}")
+        lines.append(f"           Fix: {f.fix}")
+    summary = {}
+    for f in findings:
+        summary[f.severity] = summary.get(f.severity, 0) + 1
+    lines.append("")
+    lines.append(
+        "Findings: %d (%s)"
+        % (len(findings), ", ".join(f"{k}={v}" for k, v in sorted(summary.items())))
+    )
+    return "\n".join(lines) + "\n"
+
+
+def _emit(findings, fmt: str) -> int:
+    if fmt == "json":
+        print(json.dumps([f.to_dict() for f in findings], indent=2))
+    else:
+        sys.stdout.write(_format_text(findings))
+    return 0
+
+
+def cmd_scan(args) -> int:
+    root = os.path.abspath(args.path)
+    if not os.path.isdir(root):
+        print(f"mod-audit: not a directory: {args.path}", file=sys.stderr)
+        return 2
+    findings = scan_mod(root)
+    _emit(findings, args.format)
+    if any(severity_at_least(f.severity, args.fail_on) for f in findings):
+        return 1
+    return 0
+
+
+def cmd_snapshot(args) -> int:
+    root = os.path.abspath(args.path)
+    if not os.path.isdir(root):
+        print(f"mod-audit: not a directory: {args.path}", file=sys.stderr)
+        return 2
+    manifest = build_snapshot(root)
+    manifest["generated_at"] = _dt.datetime.now(_dt.timezone.utc).isoformat()
+    manifest["root"] = root
+
+    out = args.out or os.path.join(
+        os.getcwd(), os.path.basename(root.rstrip(os.sep)) + ".snapshot"
+    )
+    os.makedirs(out, exist_ok=True)
+    path = os.path.join(out, "manifest.json")
+    with open(path, "w", encoding="utf-8") as fh:
+        json.dump(manifest, fh, indent=2, sort_keys=True)
+    print(f"mod-audit: snapshot written to {path}")
+    print(f"  files: {len(manifest['files'])}, hooks: {len(manifest['hooks'])}")
+    print("Keep this snapshot somewhere the mod updater cannot modify.")
+    return 0
+
+
+def cmd_diff(args) -> int:
+    root = os.path.abspath(args.installed_dir)
+    snap_dir = os.path.abspath(args.against)
+    manifest_path = (
+        snap_dir
+        if snap_dir.endswith(".json")
+        else os.path.join(snap_dir, "manifest.json")
+    )
+    if not os.path.isdir(root):
+        print(f"mod-audit: not a directory: {args.installed_dir}", file=sys.stderr)
+        return 2
+    try:
+        with open(manifest_path, "r", encoding="utf-8") as fh:
+            snapshot = json.load(fh)
+    except (OSError, ValueError) as exc:
+        print(f"mod-audit: cannot read snapshot {manifest_path}: {exc}", file=sys.stderr)
+        return 2
+    findings = diff_against_snapshot(root, snapshot)
+    _emit(findings, args.format)
+    if any(severity_at_least(f.severity, args.fail_on) for f in findings):
+        return 1
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="mod-audit",
+        description="Static supply-chain auditor for Claude Code Mods (local, offline, stdlib-only).",
+    )
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    s = sub.add_parser("scan", help="Audit a mod directory for supply-chain risks.")
+    s.add_argument("path", help="Path to the mod directory (e.g. ~/.claude/plugins/foo).")
+    s.add_argument("--format", choices=("text", "json"), default="text")
+    s.add_argument(
+        "--fail-on",
+        choices=SEVERITIES,
+        default="high",
+        help="Exit 1 if any finding meets this severity (default: high).",
+    )
+    s.set_defaults(func=cmd_scan)
+
+    s = sub.add_parser("snapshot", help="Save a trusted snapshot of a mod.")
+    s.add_argument("path", help="Path to the mod directory.")
+    s.add_argument("--out", help="Snapshot directory (default: ./<mod-name>.snapshot).")
+    s.set_defaults(func=cmd_snapshot)
+
+    s = sub.add_parser("diff", help="Diff an installed mod against a trusted snapshot.")
+    s.add_argument("installed_dir", help="Path to the installed mod directory.")
+    s.add_argument(
+        "--against", required=True, help="Snapshot directory or manifest.json from `snapshot`."
+    )
+    s.add_argument("--format", choices=("text", "json"), default="text")
+    s.add_argument("--fail-on", choices=SEVERITIES, default="high")
+    s.set_defaults(func=cmd_diff)
+    return p
+
+
+def main(argv=None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mod_audit/rules.py

@@ -0,0 +1,520 @@
+"""Audit rules: hooks, TypeScript source, env exfiltration, permissions.
+
+All rules are offline heuristics over static text. No code is executed.
+Findings carry a stable rule id, severity, file:line, explanation, and fix.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+from dataclasses import asdict, dataclass
+from typing import Dict, Iterator, List, Optional, Tuple
+
+SEVERITIES = ("low", "medium", "high", "critical")
+_SEV_ORDER = {s: i for i, s in enumerate(SEVERITIES)}
+
+# Duplicated from mod_audit.__init__ to avoid a circular import at module load.
+__version__ = "0.1.0"
+
+TS_EXTS = (".ts", ".js", ".mjs", ".cjs", ".tsx", ".jsx")
+CONFIG_FILES = ("plugin.json", "hooks.json", "package.json")
+SKIP_DIRS = {"node_modules", ".git", "dist", "build", "__pycache__"}
+
+
+@dataclass
+class Finding:
+    rule_id: str
+    severity: str  # low | medium | high | critical
+    file: str
+    line: int
+    message: str
+    fix: str
+
+    def to_dict(self) -> Dict:
+        return asdict(self)
+
+
+# ---------------------------------------------------------------------------
+# 1. Lifecycle hook scanning
+# ---------------------------------------------------------------------------
+
+# Hook command patterns -----------------------------------------------------
+_PIPED_DOWNLOAD = re.compile(
+    r"\b(curl|wget)\b[^|;&\n]*\|\s*(?:sudo\s+)?(sh|bash|zsh|dash|fish)\b", re.I
+)
+_B64_DECODE_EXEC = re.compile(
+    r"base64\s+(?:-d|--decode)\b|\bb64decode\b|"
+    r"\$\(\s*echo\s+[A-Za-z0-9+/=]{16,}\s*\|\s*base64",
+    re.I,
+)
+_CURL_DATA_EXFIL = re.compile(
+    r"\bcurl\b[^\n;]*?(?:-d\b|--data(?:-binary|-urlencode)?\b)", re.I
+)
+_SUDO = re.compile(r"(?:^|[\s;&|])sudo(?:\s|$)", re.I)
+_REVERSE_SHELL = re.compile(r"\b(nc|netcat|ncat|socat)\b[^|;&\n]*-e\b|/dev/tcp/", re.I)
+_CHMOD_EXEC = re.compile(r"\bchmod\s+\+x\b", re.I)
+_RM_RF = re.compile(r"\brm\s+-[a-z]*r[a-z]*f\b|\brm\s+-rf?\s+[/~]", re.I)
+
+# Keys whose string values are shell commands.
+HOOK_CMD_KEYS = {"command", "cmd", "shell", "exec", "run", "script", "entrypoint"}
+# Ancestor keys under which free-form strings are treated as hook commands.
+HOOK_SECTION_KEYS = {"hooks", "lifecycle", "scripts"}
+
+
+def _walk_hook_commands(node, ancestors: Tuple[str, ...] = ()) -> Iterator[Tuple[str, Tuple[str, ...]]]:
+    """Yield (command_string, key_path) for every shell command in a config."""
+    if isinstance(node, dict):
+        in_hooks = any(a.lower() in HOOK_SECTION_KEYS for a in ancestors)
+        for key, value in node.items():
+            key_l = str(key).lower()
+            if key_l in HOOK_CMD_KEYS and isinstance(value, str) and value.strip():
+                yield value, ancestors + (str(key),)
+            elif in_hooks and isinstance(value, str) and value.strip():
+                # Free-form string directly under a hooks/lifecycle/scripts
+                # section (e.g. {"hooks": {"setup": "npm install"}}).
+                yield value, ancestors + (str(key),)
+            else:
+                yield from _walk_hook_commands(value, ancestors + (str(key),))
+    elif isinstance(node, list):
+        in_hooks = any(a.lower() in HOOK_SECTION_KEYS for a in ancestors)
+        for idx, item in enumerate(node):
+            if in_hooks and isinstance(item, str) and item.strip():
+                yield item, ancestors + (str(idx),)
+            else:
+                yield from _walk_hook_commands(item, ancestors + (str(idx),))
+
+
+def _line_of(text: str, needle: str) -> int:
+    """Best-effort 1-based line number of needle inside text (0 if unknown)."""
+    idx = text.find(needle)
+    if idx < 0:
+        return 0
+    return text.count("\n", 0, idx) + 1
+
+
+def audit_hook_command(command: str, relfile: str, line: int) -> List[Finding]:
+    """Classify one lifecycle hook shell command into findings."""
+    out: List[Finding] = []
+    cmd = command.strip()
+
+    def add(rule_id, severity, message, fix):
+        out.append(Finding(rule_id, severity, relfile, line, message, fix))
+
+    if _PIPED_DOWNLOAD.search(cmd):
+        add(
+            "HOOK-PIPED-DOWNLOAD", "high",
+            f"Piped remote download into a shell in lifecycle hook: {cmd[:120]}",
+            "Pin and vendor the script instead of piping curl/wget into sh; "
+            "verify its checksum before execution.",
+        )
+    if _B64_DECODE_EXEC.search(cmd):
+        add(
+            "HOOK-B64-EXEC", "high",
+            f"Base64 decode piped into execution in lifecycle hook: {cmd[:120]}",
+            "Decode the payload offline, inspect it, and vendor the decoded "
+            "script instead of decoding at install time.",
+        )
+    if _CURL_DATA_EXFIL.search(cmd):
+        add(
+            "HOOK-EXFIL", "high",
+            f"Hook sends data over the network (curl --data): {cmd[:120]}",
+            "Remove data exfiltration from lifecycle hooks; move telemetry to "
+            "explicit, documented opt-in code.",
+        )
+    if _REVERSE_SHELL.search(cmd):
+        add(
+            "HOOK-REVERSE-SHELL", "critical",
+            f"Possible reverse shell in lifecycle hook: {cmd[:120]}",
+            "Remove immediately and treat the mod as compromised; reinstall "
+            "from a trusted source.",
+        )
+    if _SUDO.search(cmd):
+        add(
+            "HOOK-SUDO", "high",
+            f"Hook requests privilege escalation (sudo): {cmd[:120]}",
+            "Lifecycle hooks should never need root; drop sudo and run the "
+            "mod's setup steps manually with review.",
+        )
+    if _RM_RF.search(cmd):
+        add(
+            "HOOK-RM-RF", "high",
+            f"Destructive recursive delete in lifecycle hook: {cmd[:120]}",
+            "Scope deletions to the mod's own directory and require explicit "
+            "user confirmation.",
+        )
+    if _CHMOD_EXEC.search(cmd):
+        add(
+            "HOOK-CHMOD-EXEC", "medium",
+            f"Hook marks a file executable (chmod +x): {cmd[:120]}",
+            "Ship binaries with the executable bit already set instead of "
+            "flipping it at install time.",
+        )
+    if not out:
+        # Any remaining shell hook still runs with the user's privileges.
+        add(
+            "HOOK-SHELL-EXEC", "medium",
+            f"Shell command in lifecycle hook: {cmd[:120]}",
+            "Review the command; prefer declarative setup steps over shell "
+            "hooks where the platform allows it.",
+        )
+    return out
+
+
+def scan_hook_commands(config_text: str, relfile: str) -> List[Finding]:
+    """Parse a JSON config and audit every lifecycle hook command in it."""
+    findings: List[Finding] = []
+    try:
+        config = json.loads(config_text)
+    except (json.JSONDecodeError, ValueError):
+        return findings
+    for command, _key_path in _walk_hook_commands(config):
+        line = _line_of(config_text, command[:60])
+        findings.extend(audit_hook_command(command, relfile, line))
+    return findings
+
+
+# ---------------------------------------------------------------------------
+# 2. TypeScript / JavaScript source scanning
+# ---------------------------------------------------------------------------
+
+_CHILD_PROC_IMPORT = re.compile(
+    r"""require\s*\(\s*['"]child_process['"]\s*\)|from\s+['"]child_process['"]""",
+)
+_EXEC_CALL = re.compile(r"\b(exec|execSync|spawn|spawnSync|execFile|execFileSync)\s*\(")
+_SHELL_TRUE = re.compile(r"\bshell\s*:\s*true\b")
+_CONCAT_ARG = re.compile(r"""['"`]\s*\+|\+\s*['"`]|\$\{""")
+_EVAL = re.compile(r"\beval\s*\(|\bnew\s+Function\s*\(")
+_DYN_REQUIRE = re.compile(r"\brequire\s*\(\s*(?![\'\"`])")
+_DYN_IMPORT = re.compile(r"\bimport\s*\(\s*(?![\'\"`])")
+_ENV_SECRET = re.compile(
+    r"process\.env\.[A-Za-z0-9_]*?(?:API_KEY|TOKEN|SECRET|PRIVATE)[A-Za-z0-9_]*", re.I
+)
+_NET_SINK = re.compile(
+    r"\b(fetch|axios\.(?:get|post|put|delete|request)|https?\.request|"
+    r"XMLHttpRequest|\.post\s*\()\s*\(",
+)
+_WRITE_FILE = re.compile(r"\bwriteFile(?:Sync)?\s*\(")
+_CRON_PERSIST = re.compile(r"crontab|launchd|LaunchAgents|/etc/cron", re.I)
+
+
+def scan_ts_source(source: str, relfile: str) -> List[Finding]:
+    """Heuristic scan of one TypeScript/JavaScript file."""
+    findings: List[Finding] = []
+    lines = source.splitlines()
+
+    def add(rule_id, severity, lineno, message, fix):
+        findings.append(Finding(rule_id, severity, relfile, lineno, message, fix))
+
+    uses_child_process = bool(_CHILD_PROC_IMPORT.search(source))
+
+    for i, line in enumerate(lines, start=1):
+        stripped = line.strip()
+
+        m = _EXEC_CALL.search(stripped)
+        if m:
+            window = "\n".join(lines[i - 1 : i + 4])
+            fn = m.group(1)
+            if _SHELL_TRUE.search(window):
+                add(
+                    "TS-SHELL-TRUE", "high", i,
+                    f"{fn}() invoked with shell:true — full shell parsing of the argument",
+                    "Use execFile/spawn with an argv array and shell:false; "
+                    "never pass interpolated strings to a shell.",
+                )
+            elif _CONCAT_ARG.search(stripped) or "`" in stripped and "${" in stripped:
+                add(
+                    "TS-EXEC-CONCAT", "high", i,
+                    f"{fn}() called with a concatenated/interpolated command string",
+                    "Build the command from a fixed argv array; validate or "
+                    "allow-list any dynamic part.",
+                )
+            elif uses_child_process or fn in ("exec", "execSync"):
+                add(
+                    "TS-EXEC", "medium", i,
+                    f"child_process.{fn}() usage — verify the argument is not attacker-controlled",
+                    "Prefer execFile with argv arrays; audit where the "
+                    "command string comes from.",
+                )
+
+        if _EVAL.search(stripped):
+            add(
+                "TS-EVAL", "high", i,
+                "eval() / new Function() — dynamic code execution",
+                "Replace with static code paths; if a template is needed, use "
+                "a sandboxed expression evaluator.",
+            )
+        if _DYN_REQUIRE.search(stripped) or _DYN_IMPORT.search(stripped):
+            add(
+                "TS-DYN-IMPORT", "medium", i,
+                "Dynamic require()/import() with a non-literal specifier",
+                "Pin imports to string literals or an allow-list of module "
+                "names; resolve paths against the mod directory.",
+            )
+        if _CRON_PERSIST.search(stripped):
+            add(
+                "TS-PERSISTENCE", "high", i,
+                "Persistence mechanism referenced (cron/launchd)",
+                "A mod has no business installing persistence; remove it.",
+            )
+        if _WRITE_FILE.search(stripped) and re.search(r"process\.env\.(HOME|PATH)", stripped):
+            add(
+                "TS-DOTFILE-WRITE", "medium", i,
+                "Writes a file derived from $HOME/$PATH — possible dotfile tampering",
+                "Confine writes to the mod's own directory.",
+            )
+
+    # Env/API-key exfiltration: secret env var within a few lines of a network sink.
+    for i, line in enumerate(lines, start=1):
+        if _ENV_SECRET.search(line):
+            secret = _ENV_SECRET.search(line).group(0)
+            window = "\n".join(lines[max(0, i - 2) : i + 3])
+            if _NET_SINK.search(window):
+                sink = _NET_SINK.search(window).group(1)
+                add(
+                    "ENV-EXFIL", "high", i,
+                    f"{secret} appears near a network sink ({sink}) — possible key exfiltration",
+                    "Keep secrets out of request bodies/URLs; route network "
+                    "calls through an allow-listed host set.",
+                )
+
+    return findings
+
+
+# ---------------------------------------------------------------------------
+# 3. Permissions manifest review
+# ---------------------------------------------------------------------------
+
+def scan_permissions(config: dict, relfile: str) -> List[Finding]:
+    """Flag over-broad permissions in a mod manifest."""
+    findings: List[Finding] = []
+    perms = config.get("permissions")
+    if perms is None:
+        return findings
+
+    def add(rule_id, severity, message, fix):
+        findings.append(Finding(rule_id, severity, relfile, 0, message, fix))
+
+    if isinstance(perms, dict):
+        shell = perms.get("shell")
+        if shell in (True, "always", "allow"):
+            add(
+                "PERM-SHELL-OVERGRANT", "high",
+                "Manifest grants shell execution without per-action confirmation",
+                "Narrow to specific allow-listed commands or require explicit "
+                "user confirmation per invocation.",
+            )
+        network = perms.get("network")
+        if network in (True, "always", "allow", "*"):
+            add(
+                "PERM-NETWORK-OVERGRANT", "medium",
+                "Manifest grants unrestricted network access",
+                "Restrict to the documented host allow-list the mod actually needs.",
+            )
+        fs = perms.get("filesystem") or perms.get("fs")
+        if fs in (True, "write", "read-write", "/") or (
+            isinstance(fs, str) and fs.strip().startswith("/")
+        ):
+            add(
+                "PERM-FS-OVERGRANT", "medium",
+                "Manifest grants broad filesystem write access",
+                "Scope filesystem access to the mod's own directory.",
+            )
+        tools = perms.get("tools")
+        if isinstance(tools, list) and any(
+            str(t).lower() in ("bash", "shell", "exec", "*") for t in tools
+        ):
+            add(
+                "PERM-TOOL-SHELL", "high",
+                "Manifest grants a shell-capable tool without constraints",
+                "Remove the shell tool or bind it to an allow-listed command set.",
+            )
+    elif isinstance(perms, list):
+        lowered = [str(p).lower() for p in perms]
+        if any(p in ("shell", "bash", "exec", "*") for p in lowered):
+            add(
+                "PERM-SHELL-OVERGRANT", "high",
+                "Manifest grants shell execution permission",
+                "Narrow to specific allow-listed commands or require explicit "
+                "user confirmation per invocation.",
+            )
+        if any(p in ("network", "internet", "*") for p in lowered):
+            add(
+                "PERM-NETWORK-OVERGRANT", "medium",
+                "Manifest grants unrestricted network access",
+                "Restrict to the documented host allow-list the mod actually needs.",
+            )
+    return findings
+
+
+# ---------------------------------------------------------------------------
+# 4. Mod-level orchestration + snapshots
+# ---------------------------------------------------------------------------
+
+def _iter_mod_files(root: str) -> Iterator[Tuple[str, str]]:
+    """Yield (abspath, relpath) for auditable files, skipping vendored dirs."""
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+        for name in filenames:
+            rel = os.path.relpath(os.path.join(dirpath, name), root)
+            yield os.path.join(dirpath, name), rel
+
+
+def scan_mod(root: str) -> List[Finding]:
+    """Run every rule over a mod directory."""
+    findings: List[Finding] = []
+    for abspath, rel in _iter_mod_files(root):
+        base = os.path.basename(rel)
+        if base in CONFIG_FILES:
+            try:
+                with open(abspath, "r", encoding="utf-8", errors="replace") as fh:
+                    text = fh.read()
+            except OSError:
+                continue
+            findings.extend(scan_hook_commands(text, rel))
+            try:
+                config = json.loads(text)
+            except (json.JSONDecodeError, ValueError):
+                config = {}
+            if isinstance(config, dict):
+                findings.extend(scan_permissions(config, rel))
+        elif rel.lower().endswith(TS_EXTS):
+            try:
+                with open(abspath, "r", encoding="utf-8", errors="replace") as fh:
+                    text = fh.read()
+            except OSError:
+                continue
+            findings.extend(scan_ts_source(text, rel))
+    return findings
+
+
+def sha256_file(path: str) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as fh:
+        for chunk in iter(lambda: fh.read(65536), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def build_snapshot(root: str) -> Dict:
+    """Capture a trusted state: file hashes + hook commands + permissions."""
+    files: Dict[str, str] = {}
+    hooks: List[Dict] = []
+    permissions: Dict[str, object] = {}
+    for abspath, rel in _iter_mod_files(root):
+        try:
+            files[rel] = sha256_file(abspath)
+        except OSError:
+            continue
+        base = os.path.basename(rel)
+        if base in CONFIG_FILES:
+            try:
+                with open(abspath, "r", encoding="utf-8", errors="replace") as fh:
+                    text = fh.read()
+                config = json.loads(text)
+            except (OSError, ValueError):
+                continue
+            for command, _ in _walk_hook_commands(config):
+                hooks.append({"file": rel, "command": command})
+            if isinstance(config, dict) and config.get("permissions") is not None:
+                permissions[rel] = config["permissions"]
+    return {
+        "tool": "mod-audit",
+        "version": __version__,
+        "files": files,
+        "hooks": hooks,
+        "permissions": permissions,
+    }
+
+
+def diff_against_snapshot(root: str, snapshot: Dict) -> List[Finding]:
+    """Compare an installed mod against a trusted snapshot.
+
+    Reports new/removed/changed files, hook changes, and re-runs content
+    rules on anything new or changed — the trojanized-update audit.
+    """
+    findings: List[Finding] = []
+    old_files: Dict[str, str] = snapshot.get("files", {})
+    new_files: Dict[str, str] = {}
+    for abspath, rel in _iter_mod_files(root):
+        try:
+            new_files[rel] = sha256_file(abspath)
+        except OSError:
+            continue
+
+    def add(rule_id, severity, rel, message, fix):
+        findings.append(Finding(rule_id, severity, rel, 0, message, fix))
+
+    for rel in sorted(set(new_files) - set(old_files)):
+        add(
+            "DIFF-NEW-FILE", "medium", rel,
+            f"New file appeared since snapshot: {rel}",
+            "Verify the file is expected in this update; re-scan flagged it "
+            "below if it contains suspicious patterns.",
+        )
+    for rel in sorted(set(old_files) - set(new_files)):
+        add(
+            "DIFF-REMOVED-FILE", "low", rel,
+            f"File removed since snapshot: {rel}",
+            "Confirm the removal is part of the documented update.",
+        )
+    changed = sorted(r for r in new_files if r in old_files and new_files[r] != old_files[r])
+    for rel in changed:
+        add(
+            "DIFF-CHANGED-FILE", "medium", rel,
+            f"File changed since snapshot: {rel}",
+            "Review the change; content rules were re-run on it below.",
+        )
+
+    # Re-run content rules on new + changed files.
+    for rel in sorted(set(changed) | (set(new_files) - set(old_files))):
+        abspath = os.path.join(root, rel)
+        base = os.path.basename(rel)
+        try:
+            with open(abspath, "r", encoding="utf-8", errors="replace") as fh:
+                text = fh.read()
+        except OSError:
+            continue
+        if base in CONFIG_FILES:
+            findings.extend(scan_hook_commands(text, rel))
+            try:
+                config = json.loads(text)
+            except (json.JSONDecodeError, ValueError):
+                config = {}
+            if isinstance(config, dict):
+                findings.extend(scan_permissions(config, rel))
+        elif rel.lower().endswith(TS_EXTS):
+            findings.extend(scan_ts_source(text, rel))
+
+    # Hook inventory comparison (catches pin-swap style hook swaps).
+    old_cmds = {(h.get("file"), h.get("command")) for h in snapshot.get("hooks", [])}
+    new_cmds = set()
+    for abspath, rel in _iter_mod_files(root):
+        if os.path.basename(rel) not in CONFIG_FILES:
+            continue
+        try:
+            with open(abspath, "r", encoding="utf-8", errors="replace") as fh:
+                config = json.load(fh)
+        except (OSError, ValueError):
+            continue
+        for command, _ in _walk_hook_commands(config):
+            new_cmds.add((rel, command))
+    for rel, command in sorted(new_cmds - old_cmds):
+        add(
+            "DIFF-HOOK-CHANGED", "high", rel,
+            f"Hook command added/changed since snapshot: {command[:120]}",
+            "Treat unexpected hook changes as a compromise indicator; "
+            "reinstall from the trusted source.",
+        )
+    for rel, command in sorted(old_cmds - new_cmds):
+        add(
+            "DIFF-HOOK-REMOVED", "low", rel,
+            f"Hook command removed since snapshot: {command[:120]}",
+            "Confirm the removal is part of the documented update.",
+        )
+    return findings
+
+
+def severity_at_least(sev: str, threshold: str) -> bool:
+    return _SEV_ORDER.get(sev, 0) >= _SEV_ORDER.get(threshold, 0)

mod_audit-0.1.0.dist-info/METADATA

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: mod-audit
+Version: 0.1.0
+Summary: Static supply-chain auditor for Claude Code Mods — local, offline, stdlib-only
+Author: hao li
+License: MIT
+Project-URL: Homepage, https://github.com/hahahahahahahahah6/mod-audit
+Keywords: claude-code,mods,supply-chain,security,static-analysis,audit
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# mod-audit
+
+Static supply-chain auditor for **Claude Code Mods** — local, offline, stdlib-only.
+
+Claude Code Mods are TypeScript plugin packages that usually live under
+`~/.claude/plugins/` and run **lifecycle hooks with your shell privileges**.
+A single trojanized mod update can pipe `curl | sh` straight into your
+machine. mod-audit scans a mod before you install it, snapshots the trusted
+state, and diffs later updates against that snapshot — so a pin-swap style
+update hijack lights up instead of slipping through.
+
+Zero third-party dependencies. Python >= 3.9. No network calls, ever.
+
+## Why this exists
+
+The agent supply chain is getting hit, repeatedly, in public:
+
+- **AIR SkillJacking** — 925 skills hijacked, reaching an estimated 134k agents.
+- **Plugin4Shell** — pin-swap attacks bypass SHA-pinning on plugin updates,
+  swapping trusted code for malicious code between the pin check and install.
+- **Pwn2Own Ireland** — a Codex argument-injection flaw worth $40k showed how
+  agent tooling becomes a shell-execution primitive.
+- **SKILLCLOAK** — cloaking techniques that bypass 90%+ of existing scanners.
+
+Most defenses are either cloud-based scanners (your mod source leaves your
+machine) or metadata-only reviewers that never look at the TypeScript that
+actually runs. mod-audit does the opposite: it runs on your machine, offline,
+and reads the code.
+
+## How it differs
+
+| | mod-audit | ClawSecure Watchtower | rad-security AgentKeeper |
+|---|---|---|---|
+| Where it runs | Local / offline | Cloud scan | Cloud scan |
+| Audits Mod TypeScript source | Yes | Partial | No — plugin/skill metadata only |
+| Lifecycle hook analysis | Yes (shell patterns) | Generic | Metadata-level |
+| Trojanized-update diffing | Yes (`snapshot`/`diff`) | No | No |
+| Dependencies | Zero (stdlib only) | SaaS | SaaS |
+
+Positioning: **local + offline + Mod TypeScript code specialist**. It does not
+replace a metadata/policy reviewer — it covers the layer those tools skip:
+the code that actually executes on your box.
+
+## Install
+
+```bash
+pip install mod-audit
+```
+
+## Quick start
+
+```bash
+# 1. Audit a mod before installing it
+mod-audit scan ~/.claude/plugins/some-mod
+
+# 2. Snapshot the trusted state right after a clean install
+mod-audit snapshot ~/.claude/plugins/some-mod --out ~/snapshots/some-mod.snapshot
+
+# 3. After every update, diff against the snapshot
+mod-audit diff ~/.claude/plugins/some-mod --against ~/snapshots/some-mod.snapshot
+```
+
+JSON output for scripting:
+
+```bash
+mod-audit scan ./my-mod --format json
+```
+
+## What it checks
+
+### 1. Dangerous lifecycle hooks (`plugin.json` / `hooks.json` / `package.json`)
+
+| Rule | Severity | What it catches |
+|---|---|---|
+| `HOOK-PIPED-DOWNLOAD` | high | `curl … \| sh`, `wget … \| bash` in hooks |
+| `HOOK-B64-EXEC` | high | base64 decode piped into execution |
+| `HOOK-EXFIL` | high | `curl --data` exfiltrating data from a hook |
+| `HOOK-REVERSE-SHELL` | critical | `nc -e`, `/dev/tcp/` reverse shells |
+| `HOOK-SUDO` | high | privilege escalation in hooks |
+| `HOOK-RM-RF` | high | destructive recursive deletes |
+| `HOOK-CHMOD-EXEC` | medium | flipping files executable at install time |
+| `HOOK-SHELL-EXEC` | medium | any other shell hook (runs as you) |
+
+### 2. Shell-execution patterns in `.ts`/`.js` source
+
+| Rule | Severity | What it catches |
+|---|---|---|
+| `TS-SHELL-TRUE` | high | `exec/spawn` with `shell: true` |
+| `TS-EXEC-CONCAT` | high | concatenated/interpolated command strings |
+| `TS-EXEC` | medium | `child_process` usage to review |
+| `TS-EVAL` | high | `eval()` / `new Function()` |
+| `TS-DYN-IMPORT` | medium | dynamic `require()`/`import()` with non-literal specifiers |
+| `TS-PERSISTENCE` | high | cron/launchd persistence references |
+| `TS-DOTFILE-WRITE` | medium | writes derived from `$HOME`/`$PATH` |
+
+### 3. Env / API-key exfiltration
+
+| Rule | Severity | What it catches |
+|---|---|---|
+| `ENV-EXFIL` | high | `process.env.*(API_KEY\|TOKEN\|SECRET\|PRIVATE)` within a few lines of a network sink (`fetch`, `axios`, `http.request`, …) |
+
+### 4. Trojanized-update diff (`snapshot` / `diff`)
+
+| Rule | Severity | What it catches |
+|---|---|---|
+| `DIFF-NEW-FILE` | medium | files that appeared since the snapshot |
+| `DIFF-CHANGED-FILE` | medium | files whose hash changed |
+| `DIFF-REMOVED-FILE` | low | files that disappeared |
+| `DIFF-HOOK-CHANGED` | high | hook commands added or swapped since the snapshot |
+| `DIFF-HOOK-REMOVED` | low | hook commands removed |
+
+New and changed files are re-scanned with all content rules during `diff`.
+
+### 5. Permissions manifest review
+
+| Rule | Severity | What it catches |
+|---|---|---|
+| `PERM-SHELL-OVERGRANT` | high | shell granted without per-action confirmation |
+| `PERM-TOOL-SHELL` | high | shell-capable tool granted without constraints |
+| `PERM-NETWORK-OVERGRANT` | medium | unrestricted network access |
+| `PERM-FS-OVERGRANT` | medium | broad filesystem write access |
+
+Every finding includes the rule id, severity, `file:line`, an explanation,
+and a concrete fix.
+
+## CI integration
+
+mod-audit is CI-ready: it exits `1` when any finding meets `--fail-on`
+(default `high`), `0` when clean, `2` on usage errors.
+
+```yaml
+# .github/workflows/mod-audit.yml
+name: mod-audit
+on: [push, pull_request]
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install mod-audit
+      - run: mod-audit scan ./my-mod --format json
+```
+
+Gate updates in a scheduled job:
+
+```bash
+mod-audit diff ~/.claude/plugins/my-mod --against ~/snapshots/my-mod.snapshot --fail-on medium
+```
+
+## Limitations
+
+- **Offline heuristics, not a sandbox.** Rules are pattern-based and can miss
+  obfuscated code or flag benign code. Treat findings as triage signals.
+- **No execution.** The tool never runs mod code, which is the point — but it
+  also means runtime-only behavior (e.g. payloads fetched at runtime) is out
+  of scope.
+- **Snapshot trust.** `diff` is only as trustworthy as the snapshot: take it
+  from a clean install and store it where the mod updater cannot modify it.
+- **TypeScript via regex, not a parser.** Keeps the tool stdlib-only and fast;
+  heavily minified or dynamically generated code may need manual review.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

mod_audit-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+mod_audit/__init__.py,sha256=NHvIQ71ntL61KaJg6hPUFzHkkngWhVxG_F6Tj6n5EoY,556
+mod_audit/cli.py,sha256=53LyoS1XmI6vkkw7MYa_gD-KaTDUGpzTIrvGOZSniPQ,5001
+mod_audit/rules.py,sha256=rL6V6nuK8lUMsEWm0Cw9UwNy94Fk1AX64pI53PlVNXA,21212
+mod_audit-0.1.0.dist-info/licenses/LICENSE,sha256=OYhQDg7nxWoFtnF6J8NkFUA8NMw5TKv9a1WTXHY-fu4,1063
+mod_audit-0.1.0.dist-info/METADATA,sha256=9ro1Hec3NrNcdOXjwGEDLe4fRHgp1EguCdD8GxGLJj8,7233
+mod_audit-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+mod_audit-0.1.0.dist-info/entry_points.txt,sha256=7GAFxo2Cg17G8wSJ5n9930CiKn3IZWBVR6ZtKXH0D84,49
+mod_audit-0.1.0.dist-info/top_level.txt,sha256=SMi_PMtuX2bj8Tvu_OjkVI5wbannH0qax_J4_ETw1E0,10
+mod_audit-0.1.0.dist-info/RECORD,,

mod_audit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mod_audit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mod-audit = mod_audit.cli:main

mod_audit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hao li
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mod_audit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mod_audit