modvet 0.2.0__tar.gz

modvet-0.2.0/.github/workflows/modvet.yml

@@ -0,0 +1,22 @@
+# ModVet CI-Gate — scannt einen Mod vor jedem Merge.
+# Nutzung: Datei nach <dein-mod-repo>/.github/workflows/modvet.yml kopieren.
+name: modvet-scan
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  modvet:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install ModVet
+        run: |
+          pip install git+https://github.com/<owner>/modvet.git
+      - name: Scan mod
+        run: modvet scan . --fail-on HIGH

modvet-0.2.0/.gitignore

@@ -0,0 +1,8 @@
+.modvet-snapshot.json
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+demo-mods/

modvet-0.2.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.5
+Name: modvet
+Version: 0.2.0
+Summary: ModVet — deterministic pre-install security scanner for Claude Code mods (and later: skills, MCP servers).
+Author: Joerg Michno
+License: Apache-2.0
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# ModVet
+
+**Vet your Claude Code mods before you install them — deterministic, offline, in milliseconds.**
+
+Mods run unsandboxed inside the agent process with your full permissions. ModVet scans a mod directory for prompt-injection patterns, dangerous capabilities (shell exec, exfiltration, env/file access, permission-lift hooks, update trojans) and hardcoded secrets — no cloud, no LLM, no account. Findings with `file:line`, OWASP MCP Top 10 mapping, JSON/SARIF/human output, CI-ready exit codes.
+
+```
+modvet scan ./my-mod                    # Pre-Install-Check (human output)
+modvet scan ./my-mod --json             # machine-readable report
+modvet scan ./my-mod --format sarif     # GitHub Code Scanning kompatibel
+modvet badge --input report.json        # Status-Badge als SVG
+modvet snapshot ./my-mod                # Baseline nach sauberer Installation
+modvet diff ./my-mod --against .modvet-snapshot.json   # "The update is the attack"
+```
+
+Exit codes: `0` clean · `1` findings ≥ `--fail-on` (default HIGH) · `2` usage error.
+
+## Install (dev)
+
+```
+uv pip install -e .
+# oder: python -m modvet.cli scan ./some-mod
+```
+
+## What it checks
+
+- **Prompt Injection / Instruction Override** (EN + DE, ~400 deterministische Pattern inkl. Homoglyph-/Leet-/Base64-/Zero-Width-/Reverse-Normalisierung)
+- **Capability-Kombinationslogik:** Einzel-Capabilities (fetch, process.env, fs) sind normale Mod-Arbeit — erst KOMBINATIONEN im selben Ausdruck (Env-Read + POST, Exec + Fetch) werden gemeldet. Plus Angriffsprimitive: Shell-Pipe-Downloads, Base64-Exec, Reverse Shells, Hook-Permission-Lift, Config-Rewrite, Committed-Env-Files, npm-Lifecycle-Skripte.
+- **Mod-spezifische Detektoren (v0.2):** Prompt-Compose-Rewrite, PreToolUse-Argument-Rewrite, Update-Delta-Trojan.
+- **OWASP MCP Top 10 Mapping:** jedes Finding trägt seine MCP01–MCP10-Referenz (JSON-Feld `owasp_mcp`).
+- **Update-Drift:** `snapshot` + `diff` — re-audits nur das Delta nach jedem Mod-Update. Der Update-Mechanismus selbst ist ein Angriffspfad: „the update is the attack".
+
+## Vergleichstabelle (Stand 10/2026)
+
+| | **ModVet** | Snyk (MCP/Skills-Scan) | mcp-triage |
+|---|---|---|---|
+| Fokus | Claude-Code-Mods (+ Skills) | MCP-Server/Skills, breites DevSecOps | MCP-Server-Review |
+| Betrieb | **lokal & offline**, 0 €, kein Konto | Cloud-Konto, SaaS-Pricing | lokal/Repos |
+| Verfahren | deterministisch, keine LLM-Entscheidungen | Hybrid (inkl. proprietäre Analyse) | Review-basiert |
+| Update-Delta | **`snapshot`/`diff` re-auditiert nur Deltas** | Neuer Voll-Scan je Version | — |
+| OWASP-Mapping | MCP Top 10 im Finding-Feld | vorhanden | — |
+| Output | JSON, SARIF, Badge-SVG | SaaS-UI/API | Markdown |
+| Transparenz | jede Regel im Open Source einsehbar | teilweise proprietär | Open Source |
+
+## Benchmark
+
+12 echte Mod-Repos (awesome-claude-code-Katalog): FP-Reduktion von 1.815 auf <300 Findings (−85 %) seit der v0.1-Engine — Details in `specs/benchmark-results.md` und `specs/pattern-audit.md`.
+
+## Status
+
+v0.2 — Phase 1 abgeschlossen (FP-Reduktion, Kontext-Engine), Phase 2 (Outputs/Verteilung) im Bau. PyPI-Publish folgt auf Jörg-GO.
+
+(C) 2026 Jörg Michno. Engine portiert aus ClawGuard v0.5.0.

modvet-0.2.0/README.md

@@ -0,0 +1,53 @@
+# ModVet
+
+**Vet your Claude Code mods before you install them — deterministic, offline, in milliseconds.**
+
+Mods run unsandboxed inside the agent process with your full permissions. ModVet scans a mod directory for prompt-injection patterns, dangerous capabilities (shell exec, exfiltration, env/file access, permission-lift hooks, update trojans) and hardcoded secrets — no cloud, no LLM, no account. Findings with `file:line`, OWASP MCP Top 10 mapping, JSON/SARIF/human output, CI-ready exit codes.
+
+```
+modvet scan ./my-mod                    # Pre-Install-Check (human output)
+modvet scan ./my-mod --json             # machine-readable report
+modvet scan ./my-mod --format sarif     # GitHub Code Scanning kompatibel
+modvet badge --input report.json        # Status-Badge als SVG
+modvet snapshot ./my-mod                # Baseline nach sauberer Installation
+modvet diff ./my-mod --against .modvet-snapshot.json   # "The update is the attack"
+```
+
+Exit codes: `0` clean · `1` findings ≥ `--fail-on` (default HIGH) · `2` usage error.
+
+## Install (dev)
+
+```
+uv pip install -e .
+# oder: python -m modvet.cli scan ./some-mod
+```
+
+## What it checks
+
+- **Prompt Injection / Instruction Override** (EN + DE, ~400 deterministische Pattern inkl. Homoglyph-/Leet-/Base64-/Zero-Width-/Reverse-Normalisierung)
+- **Capability-Kombinationslogik:** Einzel-Capabilities (fetch, process.env, fs) sind normale Mod-Arbeit — erst KOMBINATIONEN im selben Ausdruck (Env-Read + POST, Exec + Fetch) werden gemeldet. Plus Angriffsprimitive: Shell-Pipe-Downloads, Base64-Exec, Reverse Shells, Hook-Permission-Lift, Config-Rewrite, Committed-Env-Files, npm-Lifecycle-Skripte.
+- **Mod-spezifische Detektoren (v0.2):** Prompt-Compose-Rewrite, PreToolUse-Argument-Rewrite, Update-Delta-Trojan.
+- **OWASP MCP Top 10 Mapping:** jedes Finding trägt seine MCP01–MCP10-Referenz (JSON-Feld `owasp_mcp`).
+- **Update-Drift:** `snapshot` + `diff` — re-audits nur das Delta nach jedem Mod-Update. Der Update-Mechanismus selbst ist ein Angriffspfad: „the update is the attack".
+
+## Vergleichstabelle (Stand 10/2026)
+
+| | **ModVet** | Snyk (MCP/Skills-Scan) | mcp-triage |
+|---|---|---|---|
+| Fokus | Claude-Code-Mods (+ Skills) | MCP-Server/Skills, breites DevSecOps | MCP-Server-Review |
+| Betrieb | **lokal & offline**, 0 €, kein Konto | Cloud-Konto, SaaS-Pricing | lokal/Repos |
+| Verfahren | deterministisch, keine LLM-Entscheidungen | Hybrid (inkl. proprietäre Analyse) | Review-basiert |
+| Update-Delta | **`snapshot`/`diff` re-auditiert nur Deltas** | Neuer Voll-Scan je Version | — |
+| OWASP-Mapping | MCP Top 10 im Finding-Feld | vorhanden | — |
+| Output | JSON, SARIF, Badge-SVG | SaaS-UI/API | Markdown |
+| Transparenz | jede Regel im Open Source einsehbar | teilweise proprietär | Open Source |
+
+## Benchmark
+
+12 echte Mod-Repos (awesome-claude-code-Katalog): FP-Reduktion von 1.815 auf <300 Findings (−85 %) seit der v0.1-Engine — Details in `specs/benchmark-results.md` und `specs/pattern-audit.md`.
+
+## Status
+
+v0.2 — Phase 1 abgeschlossen (FP-Reduktion, Kontext-Engine), Phase 2 (Outputs/Verteilung) im Bau. PyPI-Publish folgt auf Jörg-GO.
+
+(C) 2026 Jörg Michno. Engine portiert aus ClawGuard v0.5.0.

modvet-0.2.0/modvet/__init__.py

@@ -0,0 +1,3 @@
+"""ModVet — deterministic pre-install security scanner for Claude Code mods."""
+
+__version__ = "0.1.0"

modvet-0.2.0/modvet/badge.py

@@ -0,0 +1,69 @@
+"""ModVet — deterministischer SVG-Badge-Generator im Shields.io-Stil (stdlib only).
+
+Ausführen: from modvet.badge import badge_svg
+"""
+
+# risk_level -> (Statuswort, Farbe)
+LEVELS = {
+    "CLEAN": ("clean", "#4caf50"),
+    "LOW": ("low", "#8bc34a"),
+    "MEDIUM": ("warn", "#ffc107"),
+    "HIGH": ("high", "#ff9800"),
+    "CRITICAL": ("critical", "#f44336"),
+}
+UNKNOWN = ("unknown", "#9e9e9e")
+
+LABEL = "modvet"
+LABEL_COLOR = "#555555"
+TEXT_COLOR = "#ffffff"
+FONT_SIZE = 11
+CHAR_WIDTH = 7  # ~7px pro Zeichen bei Schriftgröße 11
+PAD_X = 5  # Innenabstand je Segmentrand
+HEIGHT = 20
+RADIUS = 3
+
+
+def _esc(text):
+    """Minimales XML-Escaping für Textinhalte."""
+    return str(text).replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+
+
+def _seg_width(text):
+    return CHAR_WIDTH * len(str(text)) + 2 * PAD_X
+
+
+def badge_svg(risk_level: str, findings: int, source: str = "mod") -> str:
+    """Erzeugt ein 2-Segment-SVG-Badge (Label 'modvet' + Status).
+
+    Deterministisch: gleiche Eingabe -> byte-identische Ausgabe.
+    `source` ist für künftige Nutzung reserviert und fließt nicht ins SVG ein.
+    """
+    key = str(risk_level).strip().upper()
+    status_word, status_color = LEVELS.get(key, UNKNOWN)
+    status_text = f"{status_word} · {findings}"
+
+    label_w = _seg_width(LABEL)
+    status_w = _seg_width(status_text)
+    total_w = label_w + status_w
+    label_cx = label_w / 2
+    status_cx = label_w + status_w / 2
+    baseline = HEIGHT - 6  # 14 bei Höhe 20
+
+    return (
+        f'<svg xmlns="http://www.w3.org/2000/svg" width="{total_w}" '
+        f'height="{HEIGHT}" role="img">\n'
+        f"  <title>modvet: {_esc(status_text)}</title>\n"
+        f'  <rect width="{total_w}" height="{HEIGHT}" rx="{RADIUS}" '
+        f'fill="{LABEL_COLOR}"/>\n'
+        f'  <rect x="{label_w}" width="{status_w}" height="{HEIGHT}" '
+        f'rx="{RADIUS}" fill="{status_color}"/>\n'
+        f'  <rect x="{label_w}" width="{RADIUS}" height="{HEIGHT}" '
+        f'fill="{status_color}"/>\n'
+        f'  <g fill="{TEXT_COLOR}" text-anchor="middle" '
+        f'font-family="Verdana,Geneva,DejaVu Sans,sans-serif" '
+        f'font-size="{FONT_SIZE}">\n'
+        f'    <text x="{label_cx}" y="{baseline}">{LABEL}</text>\n'
+        f'    <text x="{status_cx}" y="{baseline}">{_esc(status_text)}</text>\n'
+        f"  </g>\n"
+        "</svg>\n"
+    )

modvet-0.2.0/modvet/cli.py

@@ -0,0 +1,159 @@
+"""ModVet CLI — `modvet scan` / `modvet snapshot` / `modvet diff`.
+
+Exit-Codes: 0 = clean, 1 = Findings >= --fail-on, 2 = usage/error.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import sys
+from pathlib import Path
+
+from .core.engine import Severity, format_human, format_json
+from .mods import discover_mod_files, scan_mod
+
+SNAPSHOT_VERSION = 1
+
+
+def _manifest(root: Path) -> dict:
+    out = {}
+    for p in discover_mod_files(root):
+        rel = str(p.relative_to(root)).replace("\\", "/")
+        try:
+            data = p.read_bytes()
+        except OSError:
+            continue
+        out[rel] = {"sha256": hashlib.sha256(data).hexdigest(), "size": len(data)}
+    return out
+
+
+def cmd_scan(args: argparse.Namespace) -> int:
+    root = Path(args.path)
+    if not root.is_dir():
+        print(f"error: not a directory: {root}", file=sys.stderr)
+        return 2
+    report = scan_mod(root)
+    if getattr(args, "format", "human") == "sarif":
+        from .sarif import format_sarif
+        print(json.dumps(format_sarif(report), indent=2, ensure_ascii=False))
+    elif args.json:
+        print(format_json(report))
+    else:
+        print(format_human(report))
+    threshold = Severity[args.fail_on.upper()].score()
+    return 1 if any(f.severity.score() >= threshold for f in report.findings) else 0
+
+
+def cmd_badge(args: argparse.Namespace) -> int:
+    from .badge import badge_svg
+    src = Path(args.input)
+    try:
+        rep = json.loads(src.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as e:
+        print(f"error: report unreadable: {e}", file=sys.stderr)
+        return 2
+    level = rep.get("risk_level", "UNKNOWN")
+    findings = int(rep.get("total_findings", 0))
+    svg = badge_svg(level, findings)
+    out = Path(args.out) if args.out else Path("badge.svg")
+    out.write_text(svg, encoding="utf-8")
+    print(f"badge: {level} ({findings} findings) -> {out}")
+    return 0
+
+
+def cmd_snapshot(args: argparse.Namespace) -> int:
+    root = Path(args.path)
+    if not root.is_dir():
+        print(f"error: not a directory: {root}", file=sys.stderr)
+        return 2
+    snap = {"version": SNAPSHOT_VERSION, "files": _manifest(root)}
+    out = Path(args.out) if args.out else Path(".modvet-snapshot.json")
+    out.write_text(json.dumps(snap, indent=2, sort_keys=True), encoding="utf-8")
+    print(f"snapshot: {len(snap['files'])} files -> {out}")
+    return 0
+
+
+def cmd_diff(args: argparse.Namespace) -> int:
+    root = Path(args.path)
+    if not root.is_dir():
+        print(f"error: not a directory: {root}", file=sys.stderr)
+        return 2
+    try:
+        snap = json.loads(Path(args.against).read_text(encoding="utf-8"))
+        old = snap["files"]
+    except (OSError, KeyError, json.JSONDecodeError) as e:
+        print(f"error: snapshot unreadable: {e}", file=sys.stderr)
+        return 2
+    new = _manifest(root)
+    changed = sorted(set(new) - set(old))
+    changed += [f for f in sorted(set(new) & set(old)) if new[f]["sha256"] != old[f]["sha256"]]
+    removed = sorted(set(old) - set(new))
+    print("=== Update-Delta ===")
+    for f in changed:
+        print(f"  CHANGED  {f}")
+    for f in removed:
+        print(f"  REMOVED  {f}")
+    if not changed and not removed:
+        print("  (kein Delta — installierte Version identisch mit Snapshot)")
+        return 0
+    # Findings nur auf geänderten/neuen Dateien
+    findings = []
+    for rel in changed:
+        p = root / rel
+        if not p.is_file():
+            continue
+        try:
+            text = p.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        findings.extend(scan_mod_report_on_single_file(rel, text))
+    if findings:
+        print(f"=== Delta-Findings ({len(findings)}) ===")
+        for f in findings:
+            print(f"  [{f.severity.value}] {f.pattern_name} ({f.category}) {f.line_number}: {f.matched_text[:80]}")
+    else:
+        print("  Delta-Findings: keine")
+    threshold = Severity[args.fail_on.upper()].score()
+    return 1 if any(f.severity.score() >= threshold for f in findings) else 0
+
+
+def scan_mod_report_on_single_file(rel: str, text: str):
+    """Engine-Scan + Capability-Kombinationslogik für genau eine Datei (Delta-Pfad)."""
+    from .mods import scan_single_file
+    return scan_single_file(rel, text)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="modvet", description="ModVet — pre-install security scanner for Claude Code mods")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_scan = sub.add_parser("scan", help="Scan a mod directory")
+    p_scan.add_argument("path")
+    p_scan.add_argument("--json", action="store_true", help="JSON output")
+    p_scan.add_argument("--format", choices=["human", "sarif"], default="human", help="Output format (SARIF 2.1.0 for GitHub Code Scanning)")
+    p_scan.add_argument("--fail-on", default="HIGH", choices=["LOW", "MEDIUM", "HIGH", "CRITICAL"])
+    p_scan.set_defaults(fn=cmd_scan)
+
+    p_badge = sub.add_parser("badge", help="Generate a status badge SVG from a scan report")
+    p_badge.add_argument("--input", required=True, help="modvet scan --json report file")
+    p_badge.add_argument("--out", help="output .svg path (default: badge.svg)")
+    p_badge.set_defaults(fn=cmd_badge)
+
+    p_snap = sub.add_parser("snapshot", help="Baseline a clean mod install")
+    p_snap.add_argument("path")
+    p_snap.add_argument("--out", help="snapshot file (default: .modvet-snapshot.json)")
+    p_snap.set_defaults(fn=cmd_snapshot)
+
+    p_diff = sub.add_parser("diff", help="Diff installed mod against snapshot")
+    p_diff.add_argument("path")
+    p_diff.add_argument("--against", required=True, help="snapshot file")
+    p_diff.add_argument("--fail-on", default="HIGH", choices=["LOW", "MEDIUM", "HIGH", "CRITICAL"])
+    p_diff.set_defaults(fn=cmd_diff)
+
+    args = parser.parse_args(argv)
+    return args.fn(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

modvet-0.2.0/modvet/core/__init__.py

@@ -0,0 +1,19 @@
+"""Core engine (ported ClawGuard scanner: deterministic patterns, offline, no LLM)."""
+
+from .engine import (
+    Finding,
+    ScanReport,
+    Severity,
+    scan_text,
+    format_human,
+    format_json,
+)
+
+__all__ = [
+    "Finding",
+    "ScanReport",
+    "Severity",
+    "scan_text",
+    "format_human",
+    "format_json",
+]