agent-diff-guard 0.1.0__py3-none-any.whl

agent_diff_guard/analyze.py

@@ -0,0 +1,80 @@
+from dataclasses import dataclass
+
+SAFETY_KEYWORDS = ["never", "must not", "do not", "refuse"]
+
+DANGEROUS_PERMISSIONS = [
+    "shell_exec",
+    "sudo",
+    "rm -rf",
+    "exec(",
+    "eval(",
+    "admin_override",
+]
+
+# Coarse relative cost tier per model family, not exact pricing - just enough
+# to catch an obvious cheap-to-expensive swap.
+MODEL_COST_TIER = {
+    "claude-haiku-4-5": 1,
+    "claude-sonnet-5": 2,
+    "claude-opus-4-8": 3,
+    "gpt-4o-mini": 1,
+    "gpt-4o": 2,
+}
+
+
+@dataclass
+class Finding:
+    severity: str
+    message: str
+    rule_id: str
+
+
+def analyze(before: str, after: str) -> list[Finding]:
+    findings = []
+    before_lower = before.lower()
+    after_lower = after.lower()
+
+    for keyword in SAFETY_KEYWORDS:
+        if keyword in before_lower and keyword not in after_lower:
+            findings.append(
+                Finding(
+                    severity="HIGH",
+                    message=f"Safety instruction containing '{keyword}' was removed",
+                    rule_id="safety-keyword-removed",
+                )
+            )
+
+    for permission in DANGEROUS_PERMISSIONS:
+        if permission not in before_lower and permission in after_lower:
+            findings.append(
+                Finding(
+                    severity="HIGH",
+                    message=f"New dangerous permission added: '{permission}'",
+                    rule_id="dangerous-permission-added",
+                )
+            )
+
+    before_model = _find_model(before_lower)
+    after_model = _find_model(after_lower)
+    if (
+        before_model
+        and after_model
+        and before_model != after_model
+        and MODEL_COST_TIER[after_model] > MODEL_COST_TIER[before_model]
+    ):
+        findings.append(
+            Finding(
+                severity="MEDIUM",
+                message=f"Model changed from '{before_model}' to pricier '{after_model}'",
+                rule_id="model-cost-increase",
+            )
+        )
+
+    return findings
+
+
+def _find_model(text: str) -> str | None:
+    for model in MODEL_COST_TIER:
+        if model in text:
+            return model
+    return None

agent_diff_guard/cli.py

@@ -0,0 +1,158 @@
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from .analyze import Finding, analyze
+from .license import verify_license, PRO_PRODUCT_URL
+from .sarif import build_sarif
+from . import git_diff
+
+FREE_FILE_DETAIL_LIMIT = 3
+
+
+def _is_pro(args: argparse.Namespace) -> bool:
+    if not args.license_key:
+        return False
+    if verify_license(args.license_key):
+        return True
+    print("License key provided but could not be verified - falling back to free tier", file=sys.stderr)
+    return False
+
+
+def _visible_findings(findings: list[Finding], pro: bool) -> tuple[list[Finding], int]:
+    visible = findings if pro else [f for f in findings if f.severity == "HIGH"]
+    return visible, len(findings) - len(visible)
+
+
+def _print_findings(visible: list[Finding], hidden_count: int) -> None:
+    for finding in visible:
+        print(f"{finding.severity}: {finding.message}")
+    if hidden_count:
+        print(
+            f"{hidden_count} additional finding(s) hidden - upgrade to Pro to see them: {PRO_PRODUCT_URL}"
+        )
+
+
+def _diff(args: argparse.Namespace) -> int:
+    pro = _is_pro(args)
+    before = Path(args.before).read_text()
+    after = Path(args.after).read_text()
+
+    findings = analyze(before, after)
+    visible, hidden_count = _visible_findings(findings, pro)
+    _print_findings(visible, hidden_count)
+
+    return 1 if any(f.severity == "HIGH" for f in findings) else 0
+
+
+def _check(args: argparse.Namespace) -> int:
+    if args.format == "sarif":
+        return _check_sarif(args)
+
+    pro = _is_pro(args)
+    repo_dir = Path(args.repo).resolve()
+    paths = args.paths or git_diff.changed_files(repo_dir, args.against)
+
+    exit_code = 0
+    detail_shown = 0
+    hidden_high_files = 0
+    hidden_high_findings = 0
+
+    for path in paths:
+        before = git_diff.read_before(repo_dir, args.against, path)
+        after = git_diff.read_after(repo_dir, path)
+
+        findings = analyze(before, after)
+        has_high = any(f.severity == "HIGH" for f in findings)
+        if has_high:
+            exit_code = 1
+
+        if not findings:
+            continue
+
+        if pro or detail_shown < FREE_FILE_DETAIL_LIMIT:
+            visible, hidden_count = _visible_findings(findings, pro)
+            print(f"== {path} ==")
+            _print_findings(visible, hidden_count)
+            detail_shown += 1
+        elif has_high:
+            hidden_high_files += 1
+            hidden_high_findings += sum(1 for f in findings if f.severity == "HIGH")
+
+    if hidden_high_files:
+        print(
+            f"{hidden_high_files} more file(s) with {hidden_high_findings} HIGH finding(s) not shown "
+            f"in detail - upgrade to Pro for full per-file detail: {PRO_PRODUCT_URL}"
+        )
+
+    return exit_code
+
+
+def _check_sarif(args: argparse.Namespace) -> int:
+    if not _is_pro(args):
+        print(f"SARIF output requires a valid Pro license key. Get one: {PRO_PRODUCT_URL}", file=sys.stderr)
+        return 2
+
+    repo_dir = Path(args.repo).resolve()
+    paths = args.paths or git_diff.changed_files(repo_dir, args.against)
+
+    findings_by_path = {}
+    exit_code = 0
+    for path in paths:
+        before = git_diff.read_before(repo_dir, args.against, path)
+        after = git_diff.read_after(repo_dir, path)
+        findings = analyze(before, after)
+        if findings:
+            findings_by_path[path] = findings
+        if any(f.severity == "HIGH" for f in findings):
+            exit_code = 1
+
+    print(json.dumps(build_sarif(findings_by_path), indent=2))
+    return exit_code
+
+
+def run(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(
+        description="Flag risky changes to an AI agent config (prompt/tool-permissions/model choice)."
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    diff_parser = subparsers.add_parser("diff", help="Compare two file versions directly")
+    diff_parser.add_argument("before", help="Path to the file before the change")
+    diff_parser.add_argument("after", help="Path to the file after the change")
+    diff_parser.add_argument(
+        "--license-key",
+        default=os.environ.get("AGENT_DIFF_GUARD_LICENSE", ""),
+        help="Pro license key (or set AGENT_DIFF_GUARD_LICENSE). Verified against Gumroad.",
+    )
+    diff_parser.set_defaults(handler=_diff)
+
+    check_parser = subparsers.add_parser(
+        "check", help="Check files changed vs. a git ref (default: HEAD) - no manual diffing needed"
+    )
+    check_parser.add_argument(
+        "paths", nargs="*", help="Specific file(s) to check (default: all files changed vs. --against)"
+    )
+    check_parser.add_argument("--against", default="HEAD", help="Git ref to diff against (default: HEAD)")
+    check_parser.add_argument("--repo", default=".", help="Path to the git repo (default: current directory)")
+    check_parser.add_argument(
+        "--license-key",
+        default=os.environ.get("AGENT_DIFF_GUARD_LICENSE", ""),
+        help="Pro license key (or set AGENT_DIFF_GUARD_LICENSE). Verified against Gumroad.",
+    )
+    check_parser.add_argument(
+        "--format",
+        choices=["text", "sarif"],
+        default="text",
+        help="Output format. 'sarif' requires a valid Pro license key.",
+    )
+    check_parser.set_defaults(handler=_check)
+
+    args = parser.parse_args(argv)
+    return args.handler(args)
+
+
+def main() -> None:
+    sys.exit(run(sys.argv[1:]))

agent_diff_guard/git_diff.py

@@ -0,0 +1,28 @@
+import subprocess
+from pathlib import Path
+
+
+def changed_files(repo_dir: Path, against: str) -> list[str]:
+    result = subprocess.run(
+        ["git", "diff", "--name-only", against],
+        cwd=repo_dir,
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return [line for line in result.stdout.splitlines() if line]
+
+
+def read_before(repo_dir: Path, against: str, path: str) -> str:
+    result = subprocess.run(
+        ["git", "show", f"{against}:{path}"],
+        cwd=repo_dir,
+        capture_output=True,
+        text=True,
+    )
+    return result.stdout if result.returncode == 0 else ""
+
+
+def read_after(repo_dir: Path, path: str) -> str:
+    file_path = repo_dir / path
+    return file_path.read_text() if file_path.exists() else ""

agent_diff_guard/license.py

@@ -0,0 +1,44 @@
+import json
+import ssl
+import urllib.error
+import urllib.parse
+import urllib.request
+
+import certifi
+
+GUMROAD_VERIFY_URL = "https://api.gumroad.com/v2/licenses/verify"
+PRODUCT_ID = "Wpncwq3CMyYG2AGLxfbD7A=="
+PRO_PRODUCT_URL = "https://skitamaze.gumroad.com/l/dkybda"
+
+# Explicit CA bundle, not the system default: some Python installs (notably
+# macOS python.org builds) ship without a working local trust store, which
+# would otherwise make a genuinely valid, paid license fail closed to "invalid".
+_SSL_CONTEXT = ssl.create_default_context(cafile=certifi.where())
+
+
+def verify_license(license_key: str, product_id: str = PRODUCT_ID) -> bool:
+    if not license_key:
+        return False
+
+    data = urllib.parse.urlencode(
+        {
+            "product_id": product_id,
+            "license_key": license_key,
+            "increment_uses_count": "false",
+        }
+    ).encode()
+
+    try:
+        with urllib.request.urlopen(
+            GUMROAD_VERIFY_URL, data=data, timeout=10, context=_SSL_CONTEXT
+        ) as response:
+            body = json.loads(response.read())
+    except urllib.error.HTTPError as error:
+        try:
+            body = json.loads(error.read())
+        except (ValueError, OSError):
+            return False
+    except (urllib.error.URLError, TimeoutError, OSError, ValueError):
+        return False
+
+    return bool(body.get("success"))

agent_diff_guard/sarif.py

@@ -0,0 +1,41 @@
+from .analyze import Finding
+
+SARIF_LEVEL = {"HIGH": "error", "MEDIUM": "warning"}
+
+INFORMATION_URI = "https://github.com/agent-diff-guard/agent-diff-guard"
+
+
+def build_sarif(findings_by_path: dict[str, list[Finding]]) -> dict:
+    results = []
+    rule_ids = set()
+
+    for path, findings in findings_by_path.items():
+        for finding in findings:
+            rule_ids.add(finding.rule_id)
+            results.append(
+                {
+                    "ruleId": finding.rule_id,
+                    "level": SARIF_LEVEL.get(finding.severity, "warning"),
+                    "message": {"text": finding.message},
+                    "locations": [
+                        {"physicalLocation": {"artifactLocation": {"uri": path}}}
+                    ],
+                }
+            )
+
+    return {
+        "version": "2.1.0",
+        "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
+        "runs": [
+            {
+                "tool": {
+                    "driver": {
+                        "name": "agent-diff-guard",
+                        "informationUri": INFORMATION_URI,
+                        "rules": [{"id": rule_id} for rule_id in sorted(rule_ids)],
+                    }
+                },
+                "results": results,
+            }
+        ],
+    }

agent_diff_guard-0.1.0.dist-info/METADATA

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: agent-diff-guard
+Version: 0.1.0
+Summary: Flags risky changes to AI agent configs (prompts, tool permissions, model choice) in a diff.
+Author: Wally
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jwa-wa/agent-diff-guard
+Project-URL: Pro license, https://skitamaze.gumroad.com/l/dkybda
+Keywords: ai-agents,llm-security,prompt-injection,ci,github-actions
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Security
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: certifi
+Dynamic: license-file
+
+# agent-diff-guard
+
+Catches risky changes to an AI agent's config — system prompt, tool permissions, model choice —
+before they merge. A narrow, single-purpose CI check, not a full observability platform: point it
+at a repo and it scans every changed file against your base branch automatically.
+
+**[Get a Pro license →](https://skitamaze.gumroad.com/l/dkybda)** — full per-file detail, model
+cost-tier detection, SARIF output for GitHub code scanning.
+
+## What it catches
+
+- **Safety instructions removed** — a phrase like "must never" / "do not" / "refuse" present
+  before a change and missing after it.
+- **Dangerous tool permissions added** — `shell_exec`, `sudo`, `rm -rf`, `exec(`, `eval(`,
+  `admin_override` appearing for the first time.
+- **Model swapped to a pricier tier** (Pro) — e.g. haiku → opus, gpt-4o-mini → gpt-4o.
+
+## Install
+
+```bash
+pip install agent-diff-guard
+```
+
+## Usage
+
+### `check` — scans changed files against a git ref (recommended)
+
+```bash
+agent-diff-guard check                          # all files changed vs. HEAD, in the current repo
+agent-diff-guard check --against origin/main     # all files changed vs. another ref
+agent-diff-guard check path/to/agent_config.yaml # restrict to one file
+agent-diff-guard check --repo /path/to/repo      # run against a repo other than cwd
+agent-diff-guard check --license-key "$LICENSE"  # unlock Pro (or set AGENT_DIFF_GUARD_LICENSE)
+```
+
+Exit code is `1` if any file has a HIGH severity finding, `0` otherwise — safe to use as a CI gate.
+The exit code always reflects every scanned file, on the free tier too.
+
+Free tier shows full detail (path + findings) for the first 3 files with findings; beyond that it
+collapses into a one-line summary — the CI gate still fails correctly either way, Pro just gives
+the full per-file breakdown.
+
+```bash
+agent-diff-guard check --format sarif --license-key "$LICENSE"   # Pro: SARIF output
+```
+
+A Pro license key is verified live against Gumroad on every run. If it's invalid or unreachable,
+the tool falls back to the free tier rather than erroring out, so a network hiccup never breaks
+your CI.
+
+### `diff` — compare two file versions directly
+
+For comparing arbitrary snapshots outside a git checkout:
+
+```bash
+agent-diff-guard diff path/to/before.txt path/to/after.txt
+agent-diff-guard diff path/to/before.txt path/to/after.txt --license-key "$LICENSE"
+```
+
+## GitHub Action
+
+```yaml
+- uses: jwa-wa/agent-diff-guard@v1
+  with:
+    license-key: ${{ secrets.AGENT_DIFF_GUARD_LICENSE }}   # optional, omit for free tier
+```
+
+That's the whole setup for a `pull_request` workflow — it reads the PR's base branch automatically
+and works against a standard (shallow) checkout, no extra config needed.
+
+For a `push`-triggered workflow (no PR context), it compares against the previous commit instead;
+your checkout step needs `fetch-depth: 2` (or `0`) for that:
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 2
+- uses: jwa-wa/agent-diff-guard@v1
+```
+
+Store your license key as a repo/org secret — the Action passes it through as an environment
+variable, never a command-line argument, so it doesn't end up in job logs.
+
+| Input | Default | Purpose |
+|---|---|---|
+| `base-ref` | PR base branch | Branch to diff against. Empty = compare against previous commit. |
+| `paths` | *(all changed files)* | Space-separated list to restrict the scan to specific files. |
+| `license-key` | *(none, free tier)* | Pro license key, verified live against Gumroad. |
+
+## Pricing
+
+**Free** — the CI-gate result (pass/fail) always covers every scanned file. Full per-file detail
+for the first 3 files with findings each run.
+
+**Pro** — [get a license](https://skitamaze.gumroad.com/l/dkybda):
+- Full per-file detail for every file, not just the first 3.
+- Model cost-tier change detection.
+- SARIF output — findings show up natively in GitHub's Security tab.
+
+## License
+
+MIT

agent_diff_guard-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+agent_diff_guard/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agent_diff_guard/analyze.py,sha256=rNk4Jujt-ozVwUeP9T8EZV_UOcY17h56Vrp06yrpNzE,2121
+agent_diff_guard/cli.py,sha256=NnXqpi_hkx2L-V5jE_KpEonuSK7It9KCxABLtiwxgzE,5400
+agent_diff_guard/git_diff.py,sha256=nSgjKPz4U6LPZQc17MGS3UCyAeG83Ec7P4B_W4Q8aiI,770
+agent_diff_guard/license.py,sha256=UFQdfCKgLYxPdIc00gYpYIQzhSrS6atu34KtPRarAyM,1370
+agent_diff_guard/sarif.py,sha256=rrgeY3AR6vkHvrzzHqJccbzRwNdqLgEH_60D8k8jvIs,1344
+agent_diff_guard-0.1.0.dist-info/licenses/LICENSE,sha256=ITHwfuJ2PzIdOttUb260qcqFtr2AzAJl3bAJiJdkmGo,1062
+agent_diff_guard-0.1.0.dist-info/METADATA,sha256=emgcCIP0P50pI1ZWHYh0h-6lGGrqrGGelHz6SjN2xQo,4672
+agent_diff_guard-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+agent_diff_guard-0.1.0.dist-info/entry_points.txt,sha256=2Tr-rjYpUFWAYnj-9Wa96a8JsPyGQ4priWnwRA9PcR4,63
+agent_diff_guard-0.1.0.dist-info/top_level.txt,sha256=ehM7z1UtZd1JjQ0k5bOzlwj7vBsszns-1-NNm5wdHBE,17
+agent_diff_guard-0.1.0.dist-info/RECORD,,

agent_diff_guard-0.1.0.dist-info/WHEEL

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

agent_diff_guard-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agent-diff-guard = agent_diff_guard.cli:main

agent_diff_guard-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wally
+
+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.

agent_diff_guard-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agent_diff_guard