mod-audit 0.1.0__tar.gz

mod_audit-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,167 @@
+# 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/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mod-audit"
+version = "0.1.0"
+description = "Static supply-chain auditor for Claude Code Mods — local, offline, stdlib-only"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [{name = "hao li"}]
+keywords = ["claude-code", "mods", "supply-chain", "security", "static-analysis", "audit"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security",
+]
+
+[project.scripts]
+mod-audit = "mod_audit.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/hahahahahahahahah6/mod-audit"
+
+[tool.setuptools.packages.find]
+where = ["src"]

mod_audit-0.1.0/setup.cfg

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

mod_audit-0.1.0/src/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-0.1.0/src/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())