permdiff 0.1.0__py3-none-any.whl

permdiff/__init__.py

@@ -0,0 +1,26 @@
+"""permdiff: terraform plan for AI agent permission changes.
+
+Replays recorded agent tool calls against an authorization policy at two git
+refs and reports which decisions change.
+"""
+
+from __future__ import annotations
+
+from permdiff.api import diff, load_traces
+from permdiff.evaluators import Evaluator
+from permdiff.models import Decision, Effect, ErrorKind, Report, ToolCall, Transition
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Decision",
+    "Effect",
+    "ErrorKind",
+    "Evaluator",
+    "Report",
+    "ToolCall",
+    "Transition",
+    "__version__",
+    "diff",
+    "load_traces",
+]

permdiff/_proc.py

@@ -0,0 +1,69 @@
+"""Subprocess wrapper. Argument lists only, never a shell."""
+
+from __future__ import annotations
+
+import logging
+import os
+import subprocess
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from permdiff.errors import ProcError
+
+log = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class ProcResult:
+    """Outcome of one subprocess run."""
+
+    argv: tuple[str, ...]
+    returncode: int
+    stdout: str
+    stderr: str
+
+    @property
+    def ok(self) -> bool:
+        return self.returncode == 0
+
+
+def run(
+    argv: Sequence[str | os.PathLike[str]],
+    *,
+    cwd: Path | None = None,
+    env: Mapping[str, str] | None = None,
+    stdin: str | None = None,
+    timeout: float | None = None,
+) -> ProcResult:
+    """Run ``argv`` without a shell and capture text output.
+
+    Raises ProcError when the executable is missing; a non-zero exit is
+    returned, not raised, so callers can attach context.
+    """
+    args = tuple(os.fspath(a) for a in argv)
+    log.debug("run: %s (cwd=%s)", " ".join(args), cwd)
+    try:
+        completed = subprocess.run(  # noqa: S603  # argument list, no shell
+            args,
+            cwd=cwd,
+            env=dict(env) if env is not None else None,
+            input=stdin,
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=timeout,
+        )
+    except FileNotFoundError as exc:
+        msg = f"executable not found: {args[0]}"
+        raise ProcError(msg) from exc
+    except subprocess.TimeoutExpired as exc:
+        msg = f"timed out after {timeout}s: {args[0]}"
+        raise ProcError(msg) from exc
+    log.debug("exit %d: %s", completed.returncode, args[0])
+    return ProcResult(
+        argv=args,
+        returncode=completed.returncode,
+        stdout=completed.stdout,
+        stderr=completed.stderr,
+    )

permdiff/api.py

@@ -0,0 +1,203 @@
+"""Public Python API (FR-27): ``load_traces`` and ``diff``."""
+
+from __future__ import annotations
+
+import glob
+import logging
+import time
+from collections.abc import Mapping, Sequence
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from permdiff.errors import TraceImportError
+from permdiff.evaluators import registry as engines
+from permdiff.importers import registry as importers
+from permdiff.importers.base import ImportResult, ImportStats
+from permdiff.models import Counts, Report, ReportHeader, ToolCall
+from permdiff.models.limits import DEFAULT_MAX_RECORDS
+from permdiff.policy import PolicySource, source_for
+from permdiff.redact import new_salt
+from permdiff.replay import replay
+
+log = logging.getLogger(__name__)
+
+AUTO_FORMAT = "auto"
+
+
+def _expand(patterns: Sequence[str | Path]) -> list[Path]:
+    paths: list[Path] = []
+    for pattern in patterns:
+        text = str(pattern)
+        matches = sorted(glob.glob(text)) if glob.has_magic(text) else [text]  # noqa: PTH207
+        if not matches:
+            msg = f"--traces {text!r} matched no files"
+            raise TraceImportError(msg)
+        paths.extend(Path(m) for m in matches)
+    if not paths:
+        msg = "no trace files given; pass --traces FILE|GLOB"
+        raise TraceImportError(msg)
+    return paths
+
+
+def load_traces(
+    paths: Sequence[str | Path],
+    *,
+    fmt: str = AUTO_FORMAT,
+    strict: bool = False,
+    max_records: int = DEFAULT_MAX_RECORDS,
+    importer_options: Mapping[str, Any] | None = None,
+) -> ImportResult:
+    """Read every file (globs expanded) into canonical calls, in path order.
+
+    ``fmt`` is an importer name or ``auto`` to sniff each file (FR-5). ``importer_options``
+    reach importers that accept them (for example ``principal_from`` for OTel).
+    """
+    options = dict(importer_options or {})
+    calls: list[ToolCall] = []
+    read = skipped = 0
+    locators: list[str] = []
+    started = time.perf_counter()
+    for path in _expand(paths):
+        importer = (
+            importers.detect(path, **options)
+            if fmt == AUTO_FORMAT
+            else importers.get_for(path, fmt, **options)
+        )
+        result = importer.read(path, strict=strict, max_records=max_records)
+        calls.extend(result.calls)
+        if len(calls) > max_records:
+            msg = (
+                f"{path}: corpus exceeds max_records={max_records} across --traces files; "
+                "raise the cap or split the run"
+            )
+            raise TraceImportError(msg)
+        read += result.stats.read
+        skipped += result.stats.skipped
+        locators.extend(result.stats.skipped_locators)
+    log.info(
+        "imported %d calls (%d skipped) in %.2fs", read, skipped, time.perf_counter() - started
+    )
+    stats = ImportStats(read=read, skipped=skipped, skipped_locators=tuple(locators))
+    return ImportResult(calls=tuple(calls), stats=stats)
+
+
+def diff(
+    *,
+    traces: Sequence[ToolCall],
+    window: tuple[datetime, datetime] | None = None,
+    base: str,
+    head: str,
+    policy: str,
+    engine: str,
+    repo: Path = Path(),
+    engine_options: Mapping[str, Any] | None = None,
+    salt: bytes | None = None,
+    verify_deterministic: bool = False,
+    keep_temp: bool = False,
+    import_stats: ImportStats | None = None,
+    filtered: int = 0,
+    allow_widening: tuple[str, str] | None = None,
+) -> Report:
+    """Replay ``traces`` against ``policy`` at ``base`` and ``head``; return an unredacted Report.
+
+    Apply a ``Redactor`` built with the same ``salt`` before rendering.
+    """
+    return diff_sources(
+        traces=traces,
+        base=source_for(repo, base, policy),
+        head=source_for(repo, head, policy),
+        policy_path=policy,
+        engine=engine,
+        window=window,
+        engine_options=engine_options,
+        salt=salt,
+        verify_deterministic=verify_deterministic,
+        keep_temp=keep_temp,
+        import_stats=import_stats,
+        filtered=filtered,
+        allow_widening=allow_widening,
+    )
+
+
+def diff_sources(
+    *,
+    traces: Sequence[ToolCall],
+    window: tuple[datetime, datetime] | None = None,
+    base: PolicySource,
+    head: PolicySource,
+    policy_path: str,
+    engine: str,
+    engine_options: Mapping[str, Any] | None = None,
+    salt: bytes | None = None,
+    verify_deterministic: bool = False,
+    keep_temp: bool = False,
+    import_stats: ImportStats | None = None,
+    filtered: int = 0,
+    allow_widening: tuple[str, str] | None = None,
+) -> Report:
+    """``diff`` over explicit policy sources (git refs, the worktree, or plain directories)."""
+    evaluator = engines.resolve(engine, **dict(engine_options or {}))
+    run_salt = salt if salt is not None else new_salt()
+    started = time.perf_counter()
+    with (
+        base.materialize(keep=keep_temp) as base_policy,
+        head.materialize(keep=keep_temp) as head_policy,
+    ):
+        log.info("materialized policies in %.2fs", time.perf_counter() - started)
+        started = time.perf_counter()
+        result = replay(
+            traces,
+            evaluator,
+            base_policy,
+            head_policy,
+            verify_deterministic=verify_deterministic,
+        )
+        log.info(
+            "evaluated %d calls at both refs in %.2fs", len(traces), time.perf_counter() - started
+        )
+        header = ReportHeader(
+            base_label=base_policy.label,
+            base_sha=base_policy.sha,
+            head_label=head_policy.label,
+            head_sha=head_policy.sha,
+            is_worktree=head_policy.is_worktree,
+            policy_path=policy_path,
+            policy_files=_policy_files(head_policy.path),
+            engine=getattr(evaluator, "label", evaluator.name),
+            window=window if window is not None else _window(traces),
+            salt=run_salt.hex(),
+            undefined_policy=getattr(evaluator, "undefined_policy", None),
+            generated_at=datetime.now(tz=UTC),
+        )
+    counts = _merge_counts(result.counts, import_stats, filtered)
+    return Report(
+        header=header, transitions=result.transitions, counts=counts, allow_widening=allow_widening
+    )
+
+
+def _policy_files(root: Path, limit: int = 200) -> tuple[str, ...]:
+    """Relative paths of regular files under ``root`` (or ``root`` itself), sorted, capped."""
+    if root.is_file():
+        return (root.name,)
+    files = sorted(
+        p.relative_to(root).as_posix()
+        for p in root.rglob("*")
+        if p.is_file() and not p.name.startswith(".")
+    )
+    return tuple(files[:limit])
+
+
+def _window(traces: Sequence[ToolCall]) -> tuple[datetime, datetime] | None:
+    if not traces:
+        return None
+    stamps = [t.timestamp for t in traces]
+    return min(stamps), max(stamps)
+
+
+def _merge_counts(counts: Counts, stats: ImportStats | None, filtered: int) -> Counts:
+    imported = stats.read if stats else counts.evaluated + filtered
+    skipped = stats.skipped if stats else 0
+    return counts.model_copy(
+        update={"imported": imported, "skipped": skipped, "filtered": filtered}
+    )

permdiff/cli/__init__.py

@@ -0,0 +1 @@
+"""Command-line interface."""

permdiff/cli/_render.py

@@ -0,0 +1,115 @@
+"""Shared tail of ``diff`` and ``demo``: redact once, render, exit through the gate."""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+import click
+
+from permdiff.errors import ConfigError
+from permdiff.models import Report
+from permdiff.redact import RedactLevel, Redactor
+from permdiff.report import (
+    FailOn,
+    ReportView,
+    build_view,
+    gate,
+    render_json,
+    render_markdown,
+    render_sarif,
+    render_terminal,
+)
+from permdiff.report.grouping import DEFAULT_GROUP_BY, DEFAULT_MAX_GROUPS, DEFAULT_SAMPLES
+
+FORMATS = ("terminal", "markdown", "json", "sarif")
+PRINCIPAL_SHOWN_IN = frozenset({"terminal"})
+"""Formats that print principal ids verbatim (overview §3.6); every other format hashes them."""
+
+
+@dataclass(frozen=True)
+class OutputOptions:
+    fail_on: FailOn
+    redact: RedactLevel
+    show_args: frozenset[str]
+    fmt: str = "terminal"
+    samples: int = DEFAULT_SAMPLES
+    group_by: tuple[str, ...] = DEFAULT_GROUP_BY
+    max_groups: int = DEFAULT_MAX_GROUPS
+    show_attribution: bool = False
+    quiet: bool = False
+    no_color: bool = False
+    output: Path | None = None
+    pr_comment: bool = False
+    include_decisions: bool = False
+
+    @property
+    def show_principal(self) -> bool:
+        return self.fmt in PRINCIPAL_SHOWN_IN
+
+    def validated(self) -> OutputOptions:
+        """``--pr-comment`` forces markdown and refuses ``--redact none`` (AC-17.3)."""
+        if not self.pr_comment:
+            return self
+        if self.redact is RedactLevel.NONE:
+            msg = "--pr-comment refuses --redact none: PR comments must never carry raw trace data"
+            raise ConfigError(msg)
+        return OutputOptions(**{**self.__dict__, "fmt": "markdown"})
+
+
+def parse_show_args(text: str) -> frozenset[str]:
+    return frozenset(k.strip() for k in text.split(",") if k.strip())
+
+
+def use_color(no_color: bool) -> bool:
+    return not no_color and not os.environ.get("NO_COLOR") and sys.stdout.isatty()
+
+
+def emit_and_exit(ctx: click.Context, report: Report, opts: OutputOptions) -> None:
+    """Redact with the report's own salt, print, and exit with the gate code."""
+    redactor = Redactor(
+        level=opts.redact,
+        salt=bytes.fromhex(report.header.salt),
+        show_args=opts.show_args,
+        show_principal=opts.show_principal,
+    )
+    exit_code = gate(report, opts.fail_on)
+    view = build_view(
+        report,
+        redactor=redactor,
+        by=opts.group_by,
+        samples=opts.samples,
+        max_groups=opts.max_groups,
+        show_attribution=opts.show_attribution,
+        include_decisions=opts.include_decisions and opts.fmt == "json",
+    )
+    text = render(view, opts, exit_code=exit_code)
+    if opts.output is not None:
+        opts.output.write_text(text, encoding="utf-8")
+        click.echo(f"wrote {opts.fmt} report to {opts.output}", err=True)
+    else:
+        click.echo(text, nl=False)
+    ctx.exit(exit_code)
+
+
+def render(view: ReportView, opts: OutputOptions, *, exit_code: int) -> str:
+    if opts.fmt == "markdown":
+        return render_markdown(view, exit_code=exit_code, fail_on=opts.fail_on)
+    if opts.fmt == "sarif":
+        return render_sarif(view, exit_code=exit_code, fail_on=opts.fail_on)
+    if opts.fmt == "json":
+        return render_json(
+            view,
+            exit_code=exit_code,
+            fail_on=opts.fail_on,
+            include_decisions=opts.include_decisions,
+        )
+    return render_terminal(
+        view,
+        exit_code=exit_code,
+        fail_on=opts.fail_on,
+        quiet=opts.quiet,
+        color=use_color(opts.no_color) and opts.output is None,
+    )

permdiff/cli/check.py

@@ -0,0 +1,50 @@
+"""``permdiff check``: validate traces and compile both refs without diffing (FR-25)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import click
+
+from permdiff.cli.settings import (
+    engine_options,
+    load_filtered_traces,
+    resolve_config,
+    selection_flags,
+)
+from permdiff.errors import EXIT_OK, EXIT_TOOL_ERROR
+from permdiff.evaluators import registry
+from permdiff.policy import source_for
+
+
+@click.command("check")
+@selection_flags
+@click.pass_context
+def check_cmd(ctx: click.Context, /, **kwargs: Any) -> None:
+    """Parse the traces and compile the policy at both refs; exit 1 on any failure."""
+    repo: Path = kwargs.pop("repo")
+    opa_bin: Path | None = kwargs.pop("opa_bin")
+    config = resolve_config(ctx, repo, kwargs)
+    imported, selected = load_filtered_traces(config, kwargs)
+    click.echo(
+        f"traces: {imported.stats.read:,} calls ({imported.stats.skipped:,} skipped, "
+        f"{selected.filtered:,} filtered out)"
+    )
+    options = engine_options(config)
+    if opa_bin is not None:
+        options["opa_bin"] = opa_bin
+    evaluator = registry.resolve(config.policy.engine, **options)
+    failed = False
+    for ref in (config.policy.base, config.policy.head):
+        with source_for(repo, ref, config.policy.path).materialize() as materialized:
+            prepared = evaluator.prepare(materialized.path, label=materialized.label)
+            error = getattr(prepared, "compile_error", None)
+            prepared.close()
+        sha = f" ({materialized.sha[:12]})" if materialized.sha else ""
+        if error:
+            failed = True
+            click.echo(f"{materialized.label}{sha}: FAIL {error}")
+        else:
+            click.echo(f"{materialized.label}{sha}: ok")
+    ctx.exit(EXIT_TOOL_ERROR if failed else EXIT_OK)

permdiff/cli/convert.py

@@ -0,0 +1,62 @@
+"""``permdiff convert``: write any supported trace format as canonical permdiff JSONL (FR-7)."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from permdiff import api
+from permdiff.errors import TraceImportError
+from permdiff.importers.jsonl import FORMAT_NAME
+from permdiff.models import Source, ToolCall
+from permdiff.models.limits import DEFAULT_MAX_RECORDS
+
+
+def to_jsonl_line(call: ToolCall) -> str:
+    """Canonical JSONL: the record keeps its original source so provenance survives."""
+    source = call.source or Source(format=FORMAT_NAME, locator="")
+    return call.model_copy(update={"source": source}).model_dump_json(exclude_none=False) + "\n"
+
+
+@click.command("convert")
+@click.argument("files", nargs=-1, required=True)
+@click.option("--from", "fmt", default=api.AUTO_FORMAT, show_default=True, help="Importer name.")
+@click.option(
+    "-o",
+    "--output",
+    type=click.Path(path_type=Path, dir_okay=False),
+    default=None,
+    help="Output JSONL (default stdout).",
+)
+@click.option("--strict", is_flag=True, help="Abort on the first malformed record.")
+@click.option("--max-records", type=int, default=DEFAULT_MAX_RECORDS, show_default=True)
+@click.option("--principal-from", default=None, help="OTel: attribute path for the principal.")
+def convert_cmd(
+    files: tuple[str, ...],
+    fmt: str,
+    output: Path | None,
+    strict: bool,
+    max_records: int,
+    principal_from: str | None,
+) -> None:
+    """Convert Custody or OTel traces (or any importer's input) to permdiff JSONL."""
+    options = {"principal_from": principal_from} if principal_from else {}
+    result = api.load_traces(
+        files, fmt=fmt, strict=strict, max_records=max_records, importer_options=options
+    )
+    text = "".join(to_jsonl_line(c) for c in result.calls)
+    if output is not None:
+        try:
+            output.write_text(text, encoding="utf-8")
+        except OSError as exc:
+            msg = f"cannot write {output}: {exc.strerror or exc}"
+            raise TraceImportError(msg) from exc
+    else:
+        sys.stdout.write(text)
+    click.echo(
+        f"converted {result.stats.read:,} calls ({result.stats.skipped:,} skipped)"
+        + (f" to {output}" if output is not None else ""),
+        err=True,
+    )

permdiff/cli/demo.py

@@ -0,0 +1,90 @@
+"""``permdiff demo``: run the bundled example offline (FR-24)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from permdiff import api, demo
+from permdiff.cli._render import OutputOptions, emit_and_exit, parse_show_args
+from permdiff.cli.diff import parse_salt
+from permdiff.cli.settings import output_flags
+from permdiff.config.model import ReportConfig
+from permdiff.errors import EngineError
+from permdiff.policy import DirectorySource
+from permdiff.redact import RedactLevel
+from permdiff.report import FailOn
+from permdiff.report.grouping import validate_group_by
+
+ENGINES = ("auto", "opa", "python", "cedar")
+FALLBACK_NOTE = (
+    "note: opa is not installed, using the Python engine; run `permdiff setup opa` "
+    "then `permdiff demo --engine opa` for the Rego version"
+)
+
+
+def demo_output_options(kwargs: dict[str, Any]) -> OutputOptions:
+    """Shaping flags with the config defaults; the demo reads no permdiff.toml."""
+    defaults = ReportConfig()
+
+    def pick(flag: str, default: Any) -> Any:
+        value = kwargs.pop(flag)
+        return default if value is None else value
+
+    return OutputOptions(
+        fmt=pick("fmt_out", defaults.format),
+        fail_on=FailOn(pick("fail_on", defaults.fail_on)),
+        redact=RedactLevel(pick("redact", defaults.redact)),
+        show_args=parse_show_args(pick("show_args", "")),
+        samples=pick("samples", defaults.samples),
+        group_by=validate_group_by(pick("group_by", ",".join(defaults.group_by)).split(",")),
+        max_groups=pick("max_groups", defaults.max_groups),
+        show_attribution=bool(pick("show_attribution", defaults.show_attribution)),
+        quiet=kwargs.pop("quiet"),
+        no_color=kwargs.pop("no_color"),
+        output=kwargs.pop("output"),
+        pr_comment=kwargs.pop("pr_comment"),
+        include_decisions=kwargs.pop("include_decisions"),
+    ).validated()
+
+
+def choose_engine(requested: str) -> tuple[str, dict[str, Any]]:
+    """``auto`` picks OPA when the pinned binary is already present, else Python."""
+    from permdiff.evaluators.opa.binary import resolve_binary  # noqa: PLC0415  # keep start fast
+
+    if requested == "python":
+        return demo.ENGINE_SPEC, {}
+    if requested == "cedar":
+        return "cedar", {"resource": demo.CEDAR_RESOURCE}
+    try:
+        opa_bin = resolve_binary(download_missing=(requested == "opa"))
+    except EngineError:
+        if requested == "opa":
+            raise
+        click.echo(FALLBACK_NOTE, err=True)
+        return demo.ENGINE_SPEC, {}
+    return "opa", {"decision": demo.OPA_DECISION, "opa_bin": opa_bin}
+
+
+@click.command("demo")
+@click.option("--engine", type=click.Choice(ENGINES), default="auto", show_default=True)
+@output_flags
+@click.pass_context
+def demo_cmd(ctx: click.Context, /, **kwargs: Any) -> None:
+    """Diff two bundled policy versions over a 200-call synthetic corpus. Needs nothing else."""
+    opts = demo_output_options(kwargs)
+    salt = parse_salt(kwargs.pop("salt_hex"))
+    engine, engine_options = choose_engine(kwargs.pop("engine"))
+    imported = api.load_traces([demo.CORPUS], fmt="jsonl")
+    report = api.diff_sources(
+        traces=imported.calls,
+        base=DirectorySource(demo.POLICY_BASE, demo.BASE_LABEL),
+        head=DirectorySource(demo.POLICY_HEAD, demo.HEAD_LABEL),
+        policy_path="demo/policy",
+        engine=engine,
+        engine_options=engine_options,
+        salt=salt,
+        import_stats=imported.stats,
+    )
+    emit_and_exit(ctx, report, opts)