amagi-hookguard 0.1.0__py3-none-any.whl

amagi_hookguard/__init__.py

@@ -0,0 +1,3 @@
+"""amagi-hookguard: tested guardrail hooks for Claude Code."""
+
+__version__ = "0.1.0"

amagi_hookguard/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

amagi_hookguard/audit.py

@@ -0,0 +1,142 @@
+"""Append-only JSONL audit log of tool calls, with secrets redacted."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Iterator, List, Optional
+
+from .config import Config, claude_home
+
+ENV_VAR = "AMAGI_HOOKGUARD_AUDIT"
+MAX_FIELD = 400
+
+_REDACTIONS = [
+    (re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----.*?(-----END [A-Z ]*PRIVATE KEY-----|$)", re.S), "[REDACTED PRIVATE KEY]"),
+    (re.compile(r"\b(sk|rk|pk)-[A-Za-z0-9_-]{16,}"), "[REDACTED]"),
+    (re.compile(r"\b(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}"), "[REDACTED]"),
+    (re.compile(r"\bgithub_pat_[A-Za-z0-9_]{20,}"), "[REDACTED]"),
+    (re.compile(r"\bxox[abprs]-[A-Za-z0-9-]{10,}"), "[REDACTED]"),
+    (re.compile(r"\b(AKIA|ASIA)[0-9A-Z]{16}\b"), "[REDACTED]"),
+    (re.compile(r"\bAIza[0-9A-Za-z_-]{30,}"), "[REDACTED]"),
+    (re.compile(r"\bpypi-[A-Za-z0-9_-]{20,}"), "[REDACTED]"),
+    (re.compile(r"(?i)\b(bearer|token)\s+[A-Za-z0-9._~+/=-]{16,}"), r"\1 [REDACTED]"),
+    (
+        re.compile(r"(?i)\b([A-Za-z0-9_]*(password|passwd|secret|token|api[_-]?key)[A-Za-z0-9_]*)\s*([=:])\s*(\"[^\"]*\"|'[^']*'|[^\s\"']+)"),
+        r"\1\3[REDACTED]",
+    ),
+    (re.compile(r"(?i)(://[^:/\s@]+:)[^@\s/]+@"), r"\1[REDACTED]@"),
+]
+
+
+def redact(text: str) -> str:
+    for pattern, repl in _REDACTIONS:
+        text = pattern.sub(repl, text)
+    return text
+
+
+def _clip(text: str, limit: int = MAX_FIELD) -> str:
+    return text if len(text) <= limit else text[:limit] + f"... [+{len(text) - limit} chars]"
+
+
+def audit_path(cfg: Optional[Config] = None) -> Path:
+    env = os.environ.get(ENV_VAR)
+    if env:
+        return Path(env).expanduser()
+    if cfg is not None and cfg.audit_log:
+        return Path(cfg.audit_log).expanduser()
+    return claude_home() / "hookguard" / "audit.jsonl"
+
+
+def summarize_input(tool_name: str, tool_input: Any) -> str:
+    """One short, redacted line describing what the tool was asked to do."""
+    if not isinstance(tool_input, dict):
+        return ""
+    for key in ("command", "file_path", "notebook_path", "url", "pattern", "path", "query", "prompt", "description"):
+        value = tool_input.get(key)
+        if isinstance(value, str) and value:
+            extra = ""
+            if key == "pattern" and isinstance(tool_input.get("path"), str):
+                extra = f" in {tool_input['path']}"
+            return _clip(redact(value + extra))
+    try:
+        return _clip(redact(json.dumps(tool_input, sort_keys=True, default=str)))
+    except (TypeError, ValueError):
+        return ""
+
+
+def response_ok(response: Any) -> Optional[bool]:
+    if isinstance(response, dict):
+        if response.get("interrupted") is True or response.get("is_error") is True:
+            return False
+        if response.get("success") is False:
+            return False
+        return True
+    return None
+
+
+def response_size(response: Any) -> int:
+    if response is None:
+        return 0
+    if isinstance(response, str):
+        return len(response)
+    try:
+        return len(json.dumps(response, default=str))
+    except (TypeError, ValueError):
+        return 0
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def write(record: Dict[str, Any], cfg: Optional[Config] = None) -> Path:
+    path = audit_path(cfg)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    max_bytes = cfg.audit_max_bytes if cfg is not None else 10_000_000
+    try:
+        if max_bytes and path.exists() and path.stat().st_size > max_bytes:
+            rotated = path.with_name(path.name + ".1")
+            if rotated.exists():
+                rotated.unlink()
+            path.rename(rotated)
+    except OSError:
+        pass
+    line = json.dumps(record, ensure_ascii=False, sort_keys=False)
+    with open(path, "a", encoding="utf-8") as fh:
+        fh.write(line + "\n")
+    return path
+
+
+def read(path: Path) -> Iterator[Dict[str, Any]]:
+    if not path.exists():
+        return
+    with open(path, "r", encoding="utf-8", errors="replace") as fh:
+        for line in fh:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                rec = json.loads(line)
+            except ValueError:
+                continue
+            if isinstance(rec, dict):
+                yield rec
+
+
+def format_record(rec: Dict[str, Any]) -> str:
+    event = {"PreToolUse": "PRE ", "PostToolUse": "POST"}.get(rec.get("event", ""), (rec.get("event") or "?")[:4])
+    if rec.get("event") == "PreToolUse":
+        status = (rec.get("decision") or "allow").upper()
+    else:
+        ok = rec.get("ok")
+        status = "ok" if ok is True else ("FAIL" if ok is False else "-")
+    rule = f"  [{rec['rule']}]" if rec.get("rule") else ""
+    return f"{rec.get('ts', '?')}  {event}  {status:<5}  {rec.get('tool', '?'):<10}  {rec.get('input', '')}{rule}"
+
+
+def tail(records: List[Dict[str, Any]], n: int) -> List[Dict[str, Any]]:
+    return records[-n:] if n > 0 else records

amagi_hookguard/cli.py

@@ -0,0 +1,222 @@
+"""Command-line interface."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+from . import __version__
+
+# Everything else is imported inside the handlers: `hook` runs on every tool
+# call, so it should load as little as possible.
+
+PROG = "amagi-hookguard"
+
+
+def _parser() -> "argparse.ArgumentParser":
+    import argparse
+
+    p = argparse.ArgumentParser(
+        prog=PROG,
+        description="Guardrail hooks for Claude Code: block destructive commands, secret-file reads and "
+        "force pushes to main, log every tool call, and check your hook wiring.",
+    )
+    p.add_argument("--version", action="version", version=f"{PROG} {__version__}")
+    sub = p.add_subparsers(dest="cmd", metavar="COMMAND")
+
+    sub.add_parser("hook", help="run as a Claude Code hook (reads one event as JSON on stdin)")
+
+    pi = sub.add_parser("install", help="add hookguard to a settings.json (backs up the old file)")
+    pi.add_argument("--scope", choices=["user", "project", "local"], default="user",
+                    help="user = ~/.claude/settings.json (default), project = .claude/settings.json, "
+                    "local = .claude/settings.local.json")
+    pi.add_argument("--settings", metavar="PATH", help="write to this settings file instead of a scope")
+    pi.add_argument("--project", metavar="DIR", help="project folder for project/local scope (default: current folder)")
+    pi.add_argument("--absolute", action="store_true", help="write the full path to the executable instead of relying on PATH")
+    pi.add_argument("--dry-run", action="store_true", help="print the result without writing")
+
+    pu = sub.add_parser("uninstall", help="remove hookguard from a settings.json")
+    pu.add_argument("--scope", choices=["user", "project", "local"], default="user")
+    pu.add_argument("--settings", metavar="PATH")
+    pu.add_argument("--project", metavar="DIR")
+    pu.add_argument("--dry-run", action="store_true")
+
+    pd = sub.add_parser("doctor", help="check hook wiring in your Claude Code settings files")
+    pd.add_argument("--settings", metavar="PATH", action="append", help="check only this file (repeatable)")
+    pd.add_argument("--project", metavar="DIR", help="project folder (default: current folder)")
+    pd.add_argument("--no-exec", action="store_true", help="don't run the wired hook command with sample events")
+    pd.add_argument("--json", action="store_true", help="machine-readable output")
+
+    pc = sub.add_parser("check", help="show what hookguard would do with a command or file read")
+    pc.add_argument("command", nargs="?", help="shell command to test (as the Bash tool would run it)")
+    pc.add_argument("--read", metavar="PATH", help="test a Read of this file instead")
+    pc.add_argument("--tool", metavar="NAME", help="tool name for --input (e.g. Grep, PowerShell)")
+    pc.add_argument("--input", metavar="JSON", help="raw tool_input JSON for --tool")
+    pc.add_argument("--cwd", metavar="DIR", help="working folder for git branch lookups (default: current folder)")
+
+    sub.add_parser("rules", help="list the rules and what each one does")
+
+    pl = sub.add_parser("log", help="show the audit log")
+    pl.add_argument("-n", "--tail", type=int, default=20, metavar="N", help="last N entries (0 = all, default 20)")
+    pl.add_argument("--blocked", action="store_true", help="only calls hookguard blocked or flagged")
+    pl.add_argument("--session", metavar="ID", help="only this session id")
+    pl.add_argument("--json", action="store_true", help="raw JSON lines")
+    pl.add_argument("--path", action="store_true", help="print the audit log path and exit")
+    return p
+
+
+def _settings_target(args) -> Path:
+    from . import settings
+
+    if args.settings:
+        return Path(args.settings).expanduser()
+    return settings.scope_path(args.scope, args.project)
+
+
+def cmd_install(args) -> int:
+    from . import doctor, settings
+
+    path = _settings_target(args)
+    command = settings.hook_command(args.absolute)
+    try:
+        text, backup = settings.install(path, command, dry_run=args.dry_run)
+    except (ValueError, json.JSONDecodeError) as exc:
+        print(f"{PROG}: {path} is not valid settings JSON, nothing changed: {exc}", file=sys.stderr)
+        return 1
+    shown = doctor.display_path(path)
+    if args.dry_run:
+        print(f"Would write {shown}:\n")
+        print(text)
+        return 0
+    print(f"Wired hookguard into {shown} (PreToolUse + PostToolUse, matcher \"*\", command `{command}`).")
+    if backup:
+        print(f"Previous file saved as {doctor.display_path(backup)}")
+    print("Restart Claude Code (or open /hooks) so it picks up the change, then run: amagi-hookguard doctor")
+    return 0
+
+
+def cmd_uninstall(args) -> int:
+    from . import doctor, settings
+
+    path = _settings_target(args)
+    try:
+        removed, backup = settings.uninstall(path, dry_run=args.dry_run)
+    except (ValueError, json.JSONDecodeError) as exc:
+        print(f"{PROG}: {path} is not valid settings JSON, nothing changed: {exc}", file=sys.stderr)
+        return 1
+    shown = doctor.display_path(path)
+    if not removed:
+        print(f"No hookguard hooks found in {shown}.")
+        return 0
+    verb = "Would remove" if args.dry_run else "Removed"
+    print(f"{verb} {removed} hookguard hook(s) from {shown}.")
+    if backup:
+        print(f"Previous file saved as {doctor.display_path(backup)}")
+    return 0
+
+
+def cmd_doctor(args) -> int:
+    from . import doctor
+
+    sections = doctor.run_doctor(args.project, args.settings, execute=not args.no_exec)
+    print(doctor.to_json(sections) if args.json else doctor.render(sections))
+    return 1 if doctor.counts(sections)[doctor.FAIL] else 0
+
+
+def cmd_check(args) -> int:
+    from .config import load_config
+    from .rules import ASK, BLOCK, evaluate
+
+    cwd = os.path.abspath(args.cwd or os.getcwd())
+    if args.read:
+        tool, tool_input = "Read", {"file_path": args.read}
+    elif args.tool:
+        tool = args.tool
+        try:
+            tool_input = json.loads(args.input or "{}")
+        except ValueError as exc:
+            print(f"{PROG}: --input is not valid JSON: {exc}", file=sys.stderr)
+            return 1
+        if args.command and "command" not in tool_input:
+            tool_input["command"] = args.command
+    elif args.command:
+        tool, tool_input = "Bash", {"command": args.command}
+    else:
+        print(f"{PROG} check: give a command, --read PATH, or --tool NAME --input JSON", file=sys.stderr)
+        return 1
+    decision = evaluate(tool, tool_input, cwd, load_config(cwd))
+    label = {BLOCK: "BLOCK", ASK: "ASK"}.get(decision.action, "allow")
+    shown = tool_input.get("command") or tool_input.get("file_path") or json.dumps(tool_input)
+    line = f"{label:<5}  {tool}: {shown}"
+    if decision.rule:
+        line += f"\n       [{decision.rule}] {decision.reason}"
+    print(line)
+    return {BLOCK: 2, ASK: 3}.get(decision.action, 0)
+
+
+def cmd_rules(args) -> int:
+    from .rules import RULES
+
+    for r in RULES:
+        print(f"{r.action.upper():<5}  {r.id:<26}  {r.summary}")
+    print("\nTurn a rule off with \"disabled_rules\": [\"<id>\"] in ~/.claude/hookguard.json.")
+    return 0
+
+
+def cmd_log(args) -> int:
+    from . import audit, doctor
+    from .config import load_config
+    from .rules import ASK, BLOCK
+
+    path = audit.audit_path(load_config(os.getcwd()))
+    if args.path:
+        print(path)
+        return 0
+    records = list(audit.read(path))
+    if args.blocked:
+        records = [r for r in records if r.get("decision") in (BLOCK, ASK)]
+    if args.session:
+        records = [r for r in records if r.get("session") == args.session]
+    records = audit.tail(records, args.tail)
+    if not records:
+        print(f"No entries in {doctor.display_path(path)}.")
+        return 0
+    for rec in records:
+        print(json.dumps(rec, ensure_ascii=False) if args.json else audit.format_record(rec))
+    return 0
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8", errors="replace")
+        except (AttributeError, ValueError):
+            pass
+    if argv is None:
+        argv = sys.argv[1:]
+    # Fast path for the hook: on Python 3.13+ argparse alone pulls in ~0.3 s of
+    # imports (_colorize, dataclasses, inspect, shutil), paid on every tool call.
+    if list(argv) == ["hook"]:
+        from . import hook
+
+        return hook.run()
+    args = _parser().parse_args(argv)
+    if args.cmd is None:
+        _parser().print_help()
+        return 0
+    if args.cmd == "hook":
+        from . import hook
+
+        return hook.run()
+    handlers = {
+        "install": cmd_install,
+        "uninstall": cmd_uninstall,
+        "doctor": cmd_doctor,
+        "check": cmd_check,
+        "rules": cmd_rules,
+        "log": cmd_log,
+    }
+    return handlers[args.cmd](args)

amagi_hookguard/config.py

@@ -0,0 +1,132 @@
+"""Load hookguard.json from the user and project .claude folders.
+
+The user file can do anything. A project file (checked into a repo you may
+not control) can only add protection unless the user file sets
+"trust_project_config": true.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Dict, List, Optional
+
+CONFIG_NAME = "hookguard.json"
+DEFAULT_PROTECTED = ["main", "master"]
+
+KNOWN_KEYS = {
+    "disabled_rules",
+    "protected_branches",
+    "secret_globs",
+    "secret_allow_globs",
+    "allow_commands",
+    "ask_as_block",
+    "fail_closed",
+    "audit_log",
+    "audit_max_bytes",
+    "trust_project_config",
+}
+# Keys an untrusted project file may set: they only make the guard stricter.
+STRICTER_KEYS = {"protected_branches", "secret_globs", "ask_as_block", "fail_closed"}
+
+
+class Config:
+    # A plain class rather than a dataclass: importing dataclasses pulls in
+    # inspect and ast, which roughly doubles the hook's start-up time.
+    def __init__(self) -> None:
+        self.disabled_rules: List[str] = []
+        self.protected_branches: List[str] = list(DEFAULT_PROTECTED)
+        self.secret_globs: List[str] = []
+        self.secret_allow_globs: List[str] = []
+        self.allow_commands: List[str] = []
+        self.ask_as_block = False
+        self.fail_closed = False
+        self.audit_log: Optional[str] = None
+        self.audit_max_bytes = 10_000_000
+        self.sources: List[str] = []
+        self.notes: List[str] = []
+
+    def __repr__(self) -> str:
+        return f"Config({self.__dict__!r})"
+
+
+def claude_home() -> Path:
+    env = os.environ.get("CLAUDE_CONFIG_DIR")
+    return Path(env).expanduser() if env else Path.home() / ".claude"
+
+
+def user_config_path() -> Path:
+    return claude_home() / CONFIG_NAME
+
+
+def project_config_path(project_dir: Optional[str]) -> Optional[Path]:
+    if not project_dir:
+        return None
+    return Path(project_dir) / ".claude" / CONFIG_NAME
+
+
+def read_json(path: Path) -> Dict:
+    with open(path, "r", encoding="utf-8-sig") as fh:
+        data = json.load(fh)
+    if not isinstance(data, dict):
+        raise ValueError("top level must be a JSON object")
+    return data
+
+
+def _apply(cfg: Config, data: Dict, path: Path, trusted: bool) -> None:
+    for key, value in data.items():
+        if key not in KNOWN_KEYS:
+            cfg.notes.append(f"{path}: unknown key '{key}' ignored")
+            continue
+        if not trusted and key not in STRICTER_KEYS:
+            cfg.notes.append(
+                f"{path}: '{key}' ignored (project config can only add protection; "
+                "set \"trust_project_config\": true in your user hookguard.json to allow it)"
+            )
+            continue
+        if key in ("ask_as_block", "fail_closed"):
+            if not trusted:
+                if value is True:
+                    setattr(cfg, key, True)
+            else:
+                setattr(cfg, key, bool(value))
+        elif key in ("audit_max_bytes",):
+            try:
+                cfg.audit_max_bytes = int(value)
+            except (TypeError, ValueError):
+                cfg.notes.append(f"{path}: audit_max_bytes must be a number")
+        elif key in ("audit_log",):
+            cfg.audit_log = str(value) if value else None
+        elif key == "trust_project_config":
+            pass
+        else:
+            if not isinstance(value, list) or not all(isinstance(v, str) for v in value):
+                cfg.notes.append(f"{path}: '{key}' must be a list of strings")
+                continue
+            current = getattr(cfg, key)
+            for v in value:
+                if v not in current:
+                    current.append(v)
+
+
+def load_config(project_dir: Optional[str] = None) -> Config:
+    cfg = Config()
+    trust_project = False
+    upath = user_config_path()
+    if upath.is_file():
+        try:
+            data = read_json(upath)
+            _apply(cfg, data, upath, trusted=True)
+            trust_project = data.get("trust_project_config") is True
+            cfg.sources.append(str(upath))
+        except (OSError, ValueError) as exc:
+            cfg.notes.append(f"{upath}: could not read ({exc})")
+    ppath = project_config_path(project_dir)
+    if ppath is not None and ppath.is_file() and ppath.resolve() != upath.resolve():
+        try:
+            _apply(cfg, read_json(ppath), ppath, trusted=trust_project)
+            cfg.sources.append(str(ppath))
+        except (OSError, ValueError) as exc:
+            cfg.notes.append(f"{ppath}: could not read ({exc})")
+    return cfg