trustline-cli 0.1.0__py3-none-any.whl

trustline/__init__.py

@@ -0,0 +1,3 @@
+"""Trustline: trusted baseline + auto-rollback for AI agent configuration files."""
+
+__version__ = "0.1.0"

trustline/baseline.py

@@ -0,0 +1,126 @@
+"""Trusted baseline: SHA-256 snapshot of managed files + content copies."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import shutil
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .config import Config, normalize_relpath
+
+BASELINE_VERSION = 1
+
+
+def sha256_file(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as f:
+        for chunk in iter(lambda: f.read(65536), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def sha256_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+@dataclass
+class FileEntry:
+    sha256: str
+    copied: bool = False  # a content snapshot exists under copies/<sha>/
+    size: int = 0
+
+
+@dataclass
+class Change:
+    relpath: str
+    change_type: str  # "added" | "modified" | "deleted"
+    old_sha: str = ""
+    new_sha: str = ""
+
+
+@dataclass
+class Baseline:
+    version: int = BASELINE_VERSION
+    created_at: str = ""
+    files: dict[str, FileEntry] = field(default_factory=dict)
+
+    def to_json(self) -> dict:
+        return {
+            "version": self.version,
+            "created_at": self.created_at,
+            "files": {k: {"sha256": v.sha256, "copied": v.copied, "size": v.size} for k, v in self.files.items()},
+        }
+
+    @classmethod
+    def from_json(cls, data: dict) -> "Baseline":
+        b = cls(version=data.get("version", BASELINE_VERSION), created_at=data.get("created_at", ""))
+        for k, v in (data.get("files") or {}).items():
+            b.files[k] = FileEntry(sha256=v.get("sha256", ""), copied=bool(v.get("copied")), size=int(v.get("size", 0)))
+        return b
+
+
+def load(config: Config) -> Baseline | None:
+    p = config.baseline_path
+    if not p.exists():
+        return None
+    try:
+        return Baseline.from_json(json.loads(p.read_text(encoding="utf-8")))
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def save(config: Config, baseline: Baseline) -> Path:
+    config.ensure_dirs()
+    p = config.baseline_path
+    p.write_text(json.dumps(baseline.to_json(), indent=2, ensure_ascii=False), encoding="utf-8")
+    return p
+
+
+def snapshot(config: Config) -> Baseline:
+    """Hash every managed file; store content copies under copies/<sha> when
+    config.with_copies is set so rollback works even outside a git repo."""
+    from .discovery import discover
+
+    baseline = Baseline(created_at=time.strftime("%Y-%m-%dT%H:%M:%S%z"))
+    for path in discover(config):
+        rel = normalize_relpath(config.root, path)
+        digest = sha256_file(path)
+        entry = FileEntry(sha256=digest, size=path.stat().st_size)
+        if config.with_copies:
+            dest = config.copies_dir / digest
+            if not dest.exists():
+                dest.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(path, dest)
+            entry.copied = True
+        baseline.files[rel] = entry
+    return baseline
+
+
+def compare(config: Config, baseline: Baseline) -> list[Change]:
+    """Diff current managed files against the baseline."""
+    from .discovery import discover
+
+    changes: list[Change] = []
+    current: dict[str, Path] = {}
+    for path in discover(config):
+        rel = normalize_relpath(config.root, path)
+        current[rel] = path
+
+    for rel, path in current.items():
+        entry = baseline.files.get(rel)
+        if entry is None:
+            changes.append(Change(relpath=rel, change_type="added", new_sha=sha256_file(path)))
+        else:
+            digest = sha256_file(path)
+            if digest != entry.sha256:
+                changes.append(Change(relpath=rel, change_type="modified", old_sha=entry.sha256, new_sha=digest))
+
+    for rel in baseline.files:
+        if rel not in current:
+            changes.append(Change(relpath=rel, change_type="deleted", old_sha=baseline.files[rel].sha256))
+
+    changes.sort(key=lambda c: (c.change_type, c.relpath))
+    return changes

trustline/cli.py

@@ -0,0 +1,280 @@
+"""Trustline command-line interface."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from . import __version__
+from .baseline import compare, load, save, snapshot
+from .config import Config, is_managed, normalize_relpath
+from .hooks import install_hooks, run_check, uninstall_hooks
+from .rollback import rollback_file
+from .sarif import build_sarif
+from .scanner import scan_file, scan_root, severity_rank
+
+app = typer.Typer(add_completion=False, no_args_is_help=True, help="Trusted baseline + rollback for AI agent config files.")
+console = Console(highlight=False)
+
+_VERSION_STATE = {"root": None}
+
+
+def _make_config(root: Optional[str] = None, no_copies: bool = False, patterns: Optional[str] = None) -> Config:
+    return Config(
+        root=Path(root) if root else None,
+        patterns=patterns.split(",") if patterns else None,
+        with_copies=not no_copies,
+    )
+
+
+def _require_baseline(cfg: Config):
+    baseline = load(cfg)
+    if baseline is None:
+        console.print(
+            "[yellow]No trusted baseline yet.[/yellow] Run [bold]trustline init[/bold] first "
+            "(protect this project's agent config files)."
+        )
+        raise typer.Exit(2)
+    return baseline
+
+
+# --------------------------------------------------------------------------
+# init / status
+# --------------------------------------------------------------------------
+
+
+@app.command()
+def init(
+    root: Optional[str] = typer.Option(None, "--root", "-r", help="Project root (default: cwd)"),
+    no_copies: bool = typer.Option(False, "--no-copies", help="Do not store content snapshots (rollback then needs git)"),
+    patterns: Optional[str] = typer.Option(None, "--patterns", help="Comma-separated managed-file patterns (override)"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip the confirmation prompt"),
+):
+    """Establish a trusted baseline for managed agent-config files."""
+    cfg = _make_config(root, no_copies, patterns)
+    from .discovery import discover
+
+    files = discover(cfg)
+    if not files:
+        console.print("[red]No managed agent-config files found under this root.[/red]")
+        console.print("Nothing to protect yet. Default patterns: .claude/**, CLAUDE.md, **/AGENTS.md, ...")
+        raise typer.Exit(1)
+
+    table = Table(title=f"Files to protect ({len(files)})")
+    table.add_column("relative path")
+    for f in files:
+        table.add_row(normalize_relpath(cfg.root, f))
+    console.print(table)
+
+    if not yes:
+        ok = typer.confirm("Establish trusted baseline for these files?", default=True)
+        if not ok:
+            raise typer.Exit(1)
+
+    baseline = snapshot(cfg)
+    path = save(cfg, baseline)
+    console.print(f"[green]Baseline saved[/green] -> {path}")
+    console.print(f"{len(baseline.files)} file(s) hashed{' and snapshotted' if cfg.with_copies else ''}.")
+
+
+@app.command()
+def status(
+    root: Optional[str] = typer.Option(None, "--root", "-r", help="Project root (default: cwd)"),
+    json_out: bool = typer.Option(False, "--json", help="Emit JSON"),
+):
+    """Show which managed files differ from the trusted baseline."""
+    cfg = _make_config(root)
+    baseline = _require_baseline(cfg)
+    changes = compare(cfg, baseline)
+
+    if json_out:
+        console.print_json(data=[c.__dict__ for c in changes])
+        return
+
+    if not changes:
+        console.print("[green]Clean: all managed files match the trusted baseline.[/green]")
+        return
+
+    table = Table(title=f"{len(changes)} change(s) vs baseline")
+    table.add_column("type")
+    table.add_column("file")
+    for c in changes:
+        color = {"added": "green", "deleted": "red", "modified": "yellow"}[c.change_type]
+        table.add_row(f"[{color}]{c.change_type}[/{color}]", c.relpath)
+    console.print(table)
+    console.print("Hint: [bold]trustline rollback[/bold] restores; [bold]trustline init[/bold] re-baselines.")
+
+
+# --------------------------------------------------------------------------
+# scan
+# --------------------------------------------------------------------------
+
+
+@app.command()
+def scan(
+    files: list[str] = typer.Argument(None, help="Restrict scan to these paths (managed files only)"),
+    root: Optional[str] = typer.Option(None, "--root", "-r", help="Project root (default: cwd)"),
+    sarif: bool = typer.Option(False, "--sarif", help="Emit SARIF 2.1.0"),
+):
+    """Scan managed files for tamper / injection signals (static heuristics)."""
+    cfg = _make_config(root)
+    if files:
+        findings = []
+        for raw in files:
+            p = (cfg.root / raw) if not Path(raw).is_absolute() else Path(raw)
+            rel = normalize_relpath(cfg.root, p)
+            if not is_managed(rel, cfg.patterns):
+                console.print(f"[dim]skip (not managed): {rel}[/dim]")
+                continue
+            findings.extend(scan_file(p, cfg))
+    else:
+        findings = scan_root(cfg)
+
+    findings.sort(key=severity_rank)
+    if sarif:
+        console.print_json(data=build_sarif(findings))
+        return
+
+    if not findings:
+        console.print("[green]No tamper signals detected in managed files.[/green]")
+        return
+
+    table = Table(title=f"{len(findings)} signal(s) (static heuristics, review before acting)")
+    table.add_column("sev")
+    table.add_column("rule")
+    table.add_column("file")
+    table.add_column("detail")
+    for f in findings:
+        color = {"high": "red", "medium": "yellow", "low": "blue"}[f.severity]
+        table.add_row(f"[{color}]{f.severity}[/{color}]", f.rule_id, f.file, f.message)
+    console.print(table)
+
+
+# --------------------------------------------------------------------------
+# rollback
+# --------------------------------------------------------------------------
+
+
+@app.command()
+def rollback(
+    paths: list[str] = typer.Argument(None, help="Files to restore (relative paths); omit for --all"),
+    root: Optional[str] = typer.Option(None, "--root", "-r", help="Project root (default: cwd)"),
+    all_files: bool = typer.Option(False, "--all", help="Restore every out-of-baseline managed file"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation"),
+):
+    """Restore managed files to the trusted baseline (git or snapshots; tampered copy kept as .bak)."""
+    cfg = _make_config(root)
+    baseline = _require_baseline(cfg)
+    changes = compare(cfg, baseline)
+
+    if not changes:
+        console.print("[green]Nothing to roll back.[/green]")
+        return
+
+    if all_files:
+        targets = changes
+    elif paths:
+        wanted = {p.lstrip("./") for p in paths}
+        targets = [c for c in changes if c.relpath in wanted]
+        missing = wanted - {c.relpath for c in targets}
+        if missing:
+            console.print(f"[yellow]No change for: {', '.join(sorted(missing))}[/yellow]")
+    else:
+        console.print("[yellow]Nothing selected.[/yellow] Use --all or pass file paths.")
+        raise typer.Exit(1)
+
+    if not targets:
+        console.print("[yellow]Selected files are all clean.[/yellow]")
+        return
+
+    table = Table(title="Will restore")
+    table.add_column("type")
+    table.add_column("file")
+    for c in targets:
+        table.add_row(c.change_type, c.relpath)
+    console.print(table)
+    if not yes and not typer.confirm("Proceed with rollback?", default=False):
+        raise typer.Exit(1)
+
+    ok = 0
+    for c in targets:
+        if c.change_type == "added":
+            console.print(f"[yellow]skip (added after baseline, nothing trusted to restore to): {c.relpath}[/yellow]")
+            continue
+        result = rollback_file(cfg, c.relpath, c.old_sha)
+        if result.ok:
+            console.print(f"[green]restored[/green] {result.relpath} ({result.detail})")
+            ok += 1
+        else:
+            console.print(f"[red]failed[/red] {result.relpath}: {result.detail}")
+    console.print(f"\n{ok}/{len([c for c in targets if c.change_type != 'added'])} restored.")
+
+
+# --------------------------------------------------------------------------
+# export-sarif / hook
+# --------------------------------------------------------------------------
+
+
+@app.command("export-sarif")
+def export_sarif(
+    root: Optional[str] = typer.Option(None, "--root", "-r", help="Project root (default: cwd)"),
+):
+    """Scan all managed files and print findings as SARIF 2.1.0."""
+    cfg = _make_config(root)
+    findings = scan_root(cfg)
+    console.print_json(data=build_sarif(findings))
+
+
+@app.command("hook")
+def hook(
+    action: str = typer.Argument(..., help="install | uninstall"),
+    root: Optional[str] = typer.Option(None, "--root", "-r", help="Project root (default: cwd)"),
+):
+    """Install or uninstall Claude Code hooks for this project."""
+    cfg = _make_config(root)
+    if action == "install":
+        path = install_hooks(cfg.root)
+        console.print(f"[green]Hooks installed[/green] -> {path}")
+        console.print("Restart Claude Code. Events: SessionStart (warn), PreToolUse Write/Edit (block), InstructionsLoaded (block).")
+        return
+    if action == "uninstall":
+        removed = uninstall_hooks(cfg.root)
+        console.print("[green]Hooks removed.[/green]" if removed else "[yellow]No trustline hooks found.[/yellow]")
+        return
+    console.print(f"[red]Unknown action: {action}[/red] (install | uninstall)")
+    raise typer.Exit(1)
+
+
+@app.command("hook-check", hidden=True)
+def hook_check(
+    event: str = typer.Option(..., "--event", help="session-start | pre-tool-use | instructions-loaded"),
+    root: Optional[str] = typer.Option(None, "--root", "-r", help="Project root (default: cwd)"),
+):
+    """Entry point invoked by Claude Code hooks (reads hook JSON on stdin)."""
+    cfg = _make_config(root)
+    payload = {}
+    raw = sys.stdin.read()
+    if raw.strip():
+        try:
+            payload = json.loads(raw)
+        except json.JSONDecodeError:
+            payload = {}
+    code = run_check(cfg.root, event, payload)
+    raise typer.Exit(code)
+
+
+@app.callback()
+def _version_flag(version: bool = typer.Option(False, "--version", help="Show version")):
+    if version:
+        console.print(f"trustline {__version__}")
+        raise typer.Exit()
+
+
+if __name__ == "__main__":
+    app()

trustline/config.py

@@ -0,0 +1,116 @@
+"""Configuration: managed file patterns, state directory, tiny glob matcher."""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+from pathlib import Path, PurePosixPath
+
+# Default set of files that can steer an AI coding agent. Kept deliberately
+# narrow: patterns are matched relative to the project root.
+MANAGED_PATTERNS: list[str] = [
+    ".claude/**",
+    "CLAUDE.md",
+    "**/AGENTS.md",
+    "**/.cursorrules",
+    "**/.cursor/rules/**",
+    "**/.mcp.json",
+    "**/.codex/**",
+    "**/.github/copilot-instructions.md",
+]
+
+STATE_DIR_ENV = "TRUSTLINE_STATE_DIR"
+
+
+def default_state_dir() -> Path:
+    """State lives under ~/.config/trustline (override with env var)."""
+    override = os.environ.get(STATE_DIR_ENV)
+    if override:
+        return Path(override).expanduser()
+    return Path.home() / ".config" / "trustline"
+
+
+def glob_match(pattern: str, relpath: str) -> bool:
+    """Match a relative POSIX path against a glob supporting ``**``.
+
+    ``**`` matches any number of path segments (including zero). Pure-Python,
+    no external dependency.
+    """
+    psegs = PurePosixPath(relpath).parts
+    gsegs = pattern.split("/")
+
+    def rec(gi: int, pi: int) -> bool:
+        if gi == len(gsegs):
+            return pi == len(psegs)
+        g = gsegs[gi]
+        if g == "**":
+            if gi == len(gsegs) - 1:
+                return True
+            for k in range(pi, len(psegs) + 1):
+                if rec(gi + 1, k):
+                    return True
+            return False
+        if pi >= len(psegs):
+            return False
+        if fnmatch.fnmatchcase(psegs[pi], g):
+            return rec(gi + 1, pi + 1)
+        return False
+
+    return rec(0, 0)
+
+
+def is_managed(relpath: str, patterns: list[str] | None = None) -> bool:
+    pats = patterns if patterns is not None else MANAGED_PATTERNS
+    rp = relpath.replace(os.sep, "/")
+    if rp.startswith("./"):
+        rp = rp[2:]
+    return any(glob_match(p, rp) for p in pats)
+
+
+def normalize_relpath(root: Path, path: Path) -> str:
+    """Relative path from root using forward slashes."""
+    return path.relative_to(root).as_posix()
+
+
+def state_dir_for(root: Path, config: "Config") -> Path:
+    """Per-project baseline path (safe dirname derived from resolved root)."""
+    return config.state_dir / "projects" / _safe(root)
+
+
+def _safe(root: Path) -> str:
+    resolved = str(root.resolve()).replace(os.sep, "_").lstrip("_")
+    return resolved or "root"
+
+
+class Config:
+    """Runtime configuration (CLI options override defaults)."""
+
+    def __init__(
+        self,
+        root: Path | str | None = None,
+        patterns: list[str] | None = None,
+        state_dir: Path | str | None = None,
+        with_copies: bool = True,
+    ) -> None:
+        self.root: Path = Path(root).resolve() if root else Path.cwd().resolve()
+        self.patterns: list[str] = patterns if patterns is not None else list(MANAGED_PATTERNS)
+        self.state_dir: Path = Path(state_dir).resolve() if state_dir else default_state_dir().resolve()
+        self.with_copies = with_copies
+
+    # -- derived paths ------------------------------------------------------
+    @property
+    def project_state(self) -> Path:
+        return state_dir_for(self.root, self)
+
+    @property
+    def baseline_path(self) -> Path:
+        return self.project_state / "baseline.json"
+
+    @property
+    def copies_dir(self) -> Path:
+        return self.project_state / "copies"
+
+    def ensure_dirs(self) -> None:
+        self.project_state.mkdir(parents=True, exist_ok=True)
+        if self.with_copies:
+            self.copies_dir.mkdir(parents=True, exist_ok=True)

trustline/discovery.py

@@ -0,0 +1,36 @@
+"""Discovery of managed agent-configuration files under a project root.
+
+Walks the tree with pruning: directories that can never contain useful agent
+rules (.git, node_modules, venv, build output, caches...) are not descended
+into, which keeps scans fast on real repositories.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from .config import Config, is_managed, normalize_relpath
+
+SKIP_DIRS = {
+    ".git", ".hg", ".svn",
+    "node_modules", "bower_components",
+    ".venv", "venv", "env", ".tox", ".nox",
+    "target", "dist", "build", "out", ".next", ".nuxt", ".turbo",
+    "__pycache__", ".pytest_cache", ".mypy_cache", ".ruff_cache", ".idea", ".vscode",
+    ".terraform", ".serverless",
+}
+
+
+def discover(config: Config) -> list[Path]:
+    found: list[Path] = []
+    root = config.root
+    for dirpath, dirnames, filenames in os.walk(root):
+        # prune in place
+        dirnames[:] = sorted(d for d in dirnames if d not in SKIP_DIRS and not d.startswith(".") or d == ".claude" or d == ".cursor" or d == ".codex" or d == ".github")
+        for fname in sorted(filenames):
+            p = Path(dirpath) / fname
+            rel = normalize_relpath(root, p)
+            if is_managed(rel, config.patterns):
+                found.append(p)
+    return found