agentmandate 0.1.0__py3-none-any.whl

agentmandate/__init__.py

@@ -0,0 +1,51 @@
+"""AgentMandate: analyse what an AI agent is permitted to do.
+
+Two questions this package answers that a per-tool scanner cannot:
+
+- Given a set of individually legal tools, is there a legal call sequence that
+  breaches a limit? ``reach`` returns the sequence, not a score.
+- Did this release widen what the agent can reach? ``diff`` compares effective
+  authority rather than configuration text, because the two come apart.
+
+It also covers the ordinary single-manifest checks and replays recorded runs
+against the declaration, so it is usable without another tool alongside it.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .diff import Change, Delta, compare
+from .lint import Finding, check
+from .manifest import Mandate, ManifestError, Money, Tool, load, loads
+from .reach import Authority, Breach, Step, analyse
+from .scan import Proposal, propose, render, scan_file
+from .verify import Conformance, Observation, Violation, replay, replay_file
+
+__all__ = [
+    "Authority",
+    "Breach",
+    "Change",
+    "Conformance",
+    "Delta",
+    "Finding",
+    "Mandate",
+    "ManifestError",
+    "Money",
+    "Observation",
+    "Proposal",
+    "Step",
+    "Tool",
+    "Violation",
+    "__version__",
+    "analyse",
+    "check",
+    "compare",
+    "load",
+    "loads",
+    "propose",
+    "render",
+    "replay",
+    "replay_file",
+    "scan_file",
+]

agentmandate/cli.py

@@ -0,0 +1,173 @@
+"""Command-line entry point."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+
+from . import __version__
+from .diff import compare
+from .lint import ERROR, check
+from .manifest import ManifestError, load
+from .reach import analyse
+from .scan import scan_file
+from .verify import replay_file
+
+EXIT_OK = 0
+EXIT_FINDING = 1
+EXIT_USAGE = 2
+
+
+def _add_manifest(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("manifest", help="path to a mandate manifest (YAML or JSON)")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="mandate",
+        description=(
+            "Analyse what an AI agent is permitted to do, and what changed "
+            "between two releases."
+        ),
+    )
+    parser.add_argument("--version", action="version", version=f"agentmandate {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    lint_parser = subparsers.add_parser(
+        "lint", help="single-manifest control checks"
+    )
+    _add_manifest(lint_parser)
+    lint_parser.add_argument("--json", action="store_true", help="machine-readable output")
+
+    reach_parser = subparsers.add_parser(
+        "reach",
+        help="search for a legal call sequence that breaches a limit",
+    )
+    _add_manifest(reach_parser)
+    reach_parser.add_argument(
+        "--depth", type=int, default=None, help="override the manifest search depth"
+    )
+    reach_parser.add_argument("--json", action="store_true", help="machine-readable output")
+
+    diff_parser = subparsers.add_parser(
+        "diff", help="compare the effective authority of two manifests"
+    )
+    diff_parser.add_argument("before", help="the released manifest")
+    diff_parser.add_argument("after", help="the proposed manifest")
+    diff_parser.add_argument("--depth", type=int, default=None)
+    diff_parser.add_argument("--json", action="store_true", help="machine-readable output")
+    diff_parser.add_argument(
+        "--record",
+        action="store_true",
+        help="emit a markdown change record for a change advisory board",
+    )
+
+    verify_parser = subparsers.add_parser(
+        "verify", help="replay recorded calls against the manifest"
+    )
+    _add_manifest(verify_parser)
+    verify_parser.add_argument(
+        "--traces", required=True, help="JSON Lines file of observed tool calls"
+    )
+    verify_parser.add_argument("--json", action="store_true", help="machine-readable output")
+
+    scan_parser = subparsers.add_parser(
+        "scan",
+        help="derive a manifest skeleton from an MCP tools/list catalogue",
+    )
+    scan_parser.add_argument("catalogue", help="JSON file holding an MCP tools/list payload")
+    scan_parser.add_argument(
+        "--agent", default="unnamed-agent", help="agent name to write into the skeleton"
+    )
+
+    return parser
+
+
+def _emit(payload: dict, as_json: bool, text: str) -> None:
+    if as_json:
+        print(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        print(text)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "scan":
+        try:
+            print(scan_file(args.catalogue, args.agent), end="")
+        except (OSError, ValueError) as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return EXIT_USAGE
+        return EXIT_OK
+
+    try:
+        if args.command == "diff":
+            before = load(args.before)
+            after = load(args.after)
+        else:
+            mandate = load(args.manifest)
+    except ManifestError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_USAGE
+
+    if args.command == "lint":
+        findings = check(mandate)
+        payload = {
+            "findings": [
+                {
+                    "rule": f.rule,
+                    "severity": f.severity,
+                    "subject": f.subject,
+                    "message": f.message,
+                }
+                for f in findings
+            ]
+        }
+        text = (
+            "\n".join(f.render() for f in findings)
+            if findings
+            else "no single-manifest findings"
+        )
+        _emit(payload, args.json, text)
+        return EXIT_FINDING if any(f.severity == ERROR for f in findings) else EXIT_OK
+
+    if args.command == "reach":
+        authority = analyse(mandate, depth=args.depth)
+        if authority.breaches:
+            text = "\n\n".join(b.render() for b in authority.breaches)
+        else:
+            reached = f"{len(authority.reachable_tools)} tool(s) reachable"
+            bound = (
+                f", most extractable {authority.max_extractable}"
+                if authority.max_extractable
+                else ""
+            )
+            depth_note = (
+                f" within depth {authority.depth}"
+                + (" (search truncated)" if authority.truncated else "")
+            )
+            text = f"no reachable breach{depth_note}. {reached}{bound}"
+        _emit(authority.as_dict(), args.json, text)
+        return EXIT_FINDING if authority.breaches else EXIT_OK
+
+    if args.command == "diff":
+        delta = compare(before, after, depth=args.depth)
+        text = (
+            delta.record(args.before, args.after)
+            if args.record
+            else delta.render(args.before, args.after)
+        )
+        _emit(delta.as_dict(), args.json, text)
+        return EXIT_FINDING if delta.widened else EXIT_OK
+
+    conformance = replay_file(mandate, args.traces)
+    _emit(conformance.as_dict(), args.json, conformance.render())
+    return EXIT_OK if conformance.conformant else EXIT_FINDING
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

agentmandate/diff.py

@@ -0,0 +1,189 @@
+"""Compare the effective authority of two releases.
+
+The distinction this module exists to make: a configuration diff shows what
+somebody typed, and an authority diff shows what the agent can now do. They
+come apart often enough to matter. Adding one read-only tool is two lines of
+YAML and can open a path that did not exist, because reachability composes and
+text does not.
+
+The output is deliberately shaped for CI. A widening change exits non-zero so a
+pull request stops, and the change record it prints is the artefact a change
+advisory board actually wants.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from decimal import Decimal
+
+from .manifest import Mandate
+from .reach import Authority, analyse
+
+WIDENING = "widening"
+NARROWING = "narrowing"
+NEUTRAL = "neutral"
+
+
+@dataclass(frozen=True)
+class Change:
+    direction: str
+    kind: str
+    detail: str
+
+    def render(self) -> str:
+        marker = {WIDENING: "+", NARROWING: "-", NEUTRAL: "="}[self.direction]
+        return f"  {marker} {self.kind}: {self.detail}"
+
+
+@dataclass(frozen=True)
+class Delta:
+    before: Authority
+    after: Authority
+    changes: tuple[Change, ...]
+    after_agent: str = "agent"
+
+    @property
+    def direction(self) -> str:
+        if any(c.direction == WIDENING for c in self.changes):
+            return WIDENING
+        if any(c.direction == NARROWING for c in self.changes):
+            return NARROWING
+        return NEUTRAL
+
+    @property
+    def widened(self) -> bool:
+        return self.direction == WIDENING
+
+    def render(self, before_label: str = "before", after_label: str = "after") -> str:
+        lines = [f"authority diff  {before_label} -> {after_label}"]
+        if not self.changes:
+            lines.append("  = no change in effective authority")
+        else:
+            lines.extend(change.render() for change in self.changes)
+        lines.append("")
+        lines.append(f"verdict: {self.direction.upper()}")
+        if self.widened:
+            lines.append("a widening change needs named review before release")
+        return "\n".join(lines)
+
+    def record(self, before_label: str = "before", after_label: str = "after") -> str:
+        """A change record in the shape a change advisory board asks for.
+
+        The point of emitting this from the tool rather than leaving it to a
+        human is that the authority section is then derived rather than
+        asserted. A change record where somebody typed "no permission changes"
+        is worth very little.
+        """
+        widening = [c for c in self.changes if c.direction == WIDENING]
+        narrowing = [c for c in self.changes if c.direction == NARROWING]
+        lines = [
+            "# Agent authority change record",
+            "",
+            f"- **Agent:** {self.after_agent}",
+            f"- **Compared:** `{before_label}` against `{after_label}`",
+            f"- **Verdict:** {self.direction.upper()}",
+            f"- **Search depth:** {self.after.depth}"
+            + (" (truncated)" if self.after.truncated else ""),
+            "",
+            "## Authority gained",
+            "",
+        ]
+        lines.extend([f"- {c.kind}: {c.detail}" for c in widening] or ["- none"])
+        lines.extend(["", "## Authority removed", ""])
+        lines.extend([f"- {c.kind}: {c.detail}" for c in narrowing] or ["- none"])
+        lines.extend(["", "## Reachable breaches after this change", ""])
+        lines.extend(
+            [f"- {b.detail}" for b in self.after.breaches]
+            or ["- none within the search depth"]
+        )
+        lines.extend(["", "## Review", ""])
+        if self.widened:
+            lines.append(
+                "This change widens what the agent is permitted to do. It needs a "
+                "named reviewer who accepts the gained authority above."
+            )
+        else:
+            lines.append(
+                "This change does not widen what the agent is permitted to do."
+            )
+        lines.append("")
+        lines.append(
+            "Authority is computed from the manifests by bounded reachability. "
+            "An unchanged manifest does not prove unchanged authority if a tool "
+            "implementation, connector, or downstream role changed."
+        )
+        return "\n".join(lines)
+
+    def as_dict(self) -> dict:
+        return {
+            "direction": self.direction,
+            "changes": [
+                {"direction": c.direction, "kind": c.kind, "detail": c.detail}
+                for c in self.changes
+            ],
+            "before": self.before.as_dict(),
+            "after": self.after.as_dict(),
+        }
+
+
+def _set_change(
+    kind: str, before: frozenset[str], after: frozenset[str]
+) -> list[Change]:
+    changes: list[Change] = []
+    for gained in sorted(after - before):
+        changes.append(Change(WIDENING, kind, f"gained {gained}"))
+    for lost in sorted(before - after):
+        changes.append(Change(NARROWING, kind, f"lost {lost}"))
+    return changes
+
+
+def compare(before: Mandate, after: Mandate, depth: int | None = None) -> Delta:
+    """Diff the reachable authority of two mandates."""
+    lhs = analyse(before, depth=depth)
+    rhs = analyse(after, depth=depth)
+    changes: list[Change] = []
+
+    changes.extend(_set_change("tool", lhs.reachable_tools, rhs.reachable_tools))
+    changes.extend(
+        _set_change(
+            "ungated irreversible",
+            lhs.ungated_irreversible,
+            rhs.ungated_irreversible,
+        )
+    )
+    changes.extend(
+        _set_change(
+            "service principal",
+            lhs.service_principal_tools,
+            rhs.service_principal_tools,
+        )
+    )
+
+    before_effects = frozenset(f"{effect} on {scope}" for effect, scope in lhs.effects)
+    after_effects = frozenset(f"{effect} on {scope}" for effect, scope in rhs.effects)
+    changes.extend(_set_change("effect", before_effects, after_effects))
+
+    lhs_max = lhs.max_extractable.amount if lhs.max_extractable else Decimal(0)
+    rhs_max = rhs.max_extractable.amount if rhs.max_extractable else Decimal(0)
+    if rhs_max != lhs_max:
+        currency = (
+            rhs.max_extractable.currency
+            if rhs.max_extractable
+            else (lhs.max_extractable.currency if lhs.max_extractable else "")
+        )
+        direction = WIDENING if rhs_max > lhs_max else NARROWING
+        changes.append(
+            Change(
+                direction,
+                "extractable value",
+                f"{lhs_max} -> {rhs_max} {currency}".strip(),
+            )
+        )
+
+    before_breaches = frozenset(b.kind for b in lhs.breaches)
+    after_breaches = frozenset(b.kind for b in rhs.breaches)
+    changes.extend(_set_change("reachable breach", before_breaches, after_breaches))
+
+    return Delta(
+        before=lhs, after=rhs, changes=tuple(changes), after_agent=after.agent
+    )

agentmandate/lint.py

@@ -0,0 +1,149 @@
+"""Single-manifest checks.
+
+These are the defects visible in one manifest without walking the graph. Other
+agent scanners cover much of this ground, and that overlap is deliberate: a
+tool that only reported compound findings would be unusable without also
+running one of them. The checks here are the floor, not the contribution.
+
+Every finding names the control it comes from, because in a regulated setting
+"the linter says no" carries less weight than "this breaks separation of
+duties, and here is the pair of tools that proves it".
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .manifest import CALLER, IRREVERSIBLE, SERVICE, Mandate
+
+ERROR = "error"
+WARNING = "warning"
+
+
+@dataclass(frozen=True)
+class Finding:
+    rule: str
+    severity: str
+    subject: str
+    message: str
+
+    def render(self) -> str:
+        return f"{self.severity.upper():7} {self.rule:24} {self.subject}\n        {self.message}"
+
+
+def _separation_of_duties(mandate: Mandate) -> list[Finding]:
+    """One principal must not hold both sides of a maker-checker control.
+
+    NIST separates static conflict, where the role assignment itself is wrong,
+    from dynamic conflict enforced at access time. A manifest can only settle
+    the static half, so that is what this reports.
+    """
+    findings: list[Finding] = []
+    proposers = set(mandate.roles.get("proposer", ()))
+    approvers = set(mandate.roles.get("approver", ()))
+    if not proposers or not approvers:
+        return findings
+    if proposers & approvers:
+        overlap = ", ".join(sorted(proposers & approvers))
+        findings.append(
+            Finding(
+                rule="sod.same-tool",
+                severity=ERROR,
+                subject=overlap,
+                message=(
+                    "the same tool is listed as both proposer and approver, "
+                    "so the control approves itself"
+                ),
+            )
+        )
+    # The agent holds both sides even when the tools differ, because a single
+    # identity can call either one. An approve tool the proposing agent can
+    # invoke is not an independent second pair of eyes.
+    findings.append(
+        Finding(
+            rule="sod.single-identity",
+            severity=ERROR,
+            subject=f"{min(proposers)} + {min(approvers)}",
+            message=(
+                "one agent identity reaches both the proposer and the approver "
+                "role, so maker-checker is not enforced. The approver must be a "
+                "human or an independently authorised service the agent cannot "
+                "invoke"
+            ),
+        )
+    )
+    return findings
+
+
+def check(mandate: Mandate) -> list[Finding]:
+    """Run every single-manifest rule and return findings, worst first."""
+    findings: list[Finding] = []
+    findings.extend(_separation_of_duties(mandate))
+
+    for tool in mandate.tools:
+        if tool.effect == IRREVERSIBLE and not tool.requires_approval:
+            findings.append(
+                Finding(
+                    rule="effect.ungated-irreversible",
+                    severity=ERROR,
+                    subject=tool.name,
+                    message=(
+                        "an irreversible effect with no approval requirement. "
+                        "Reversibility, not confidence, decides where a gate belongs"
+                    ),
+                )
+            )
+        if tool.principal == SERVICE:
+            findings.append(
+                Finding(
+                    rule="identity.service-principal",
+                    severity=ERROR if tool.effect != "read" else WARNING,
+                    subject=tool.name,
+                    message=(
+                        "the call spends a service account rather than the "
+                        f"caller's identity, which is the confused-deputy shape. "
+                        f"Exchange the caller token instead (principal: {CALLER})"
+                    ),
+                )
+            )
+        if tool.spends_value and tool.scope_key not in tool.requires:
+            findings.append(
+                Finding(
+                    rule="ceiling.unbound-scope",
+                    severity=ERROR,
+                    subject=tool.name,
+                    message=(
+                        f"the ceiling is measured against {tool.scope_key!r}, but the "
+                        "tool does not require that scope, so the bound is not "
+                        "attached to anything the caller was authorised for"
+                    ),
+                )
+            )
+        if tool.unbounded and tool.produces is None:
+            findings.append(
+                Finding(
+                    rule="scope.unbounded-nothing",
+                    severity=WARNING,
+                    subject=tool.name,
+                    message="marked unbounded but produces no scope, so the flag has no effect",
+                )
+            )
+
+    currencies = {t.ceiling.currency for t in mandate.tools if t.ceiling}
+    if mandate.limits.total is not None:
+        currencies.add(mandate.limits.total.currency)
+    if len(currencies) > 1:
+        findings.append(
+            Finding(
+                rule="ceiling.mixed-currency",
+                severity=ERROR,
+                subject=", ".join(sorted(currencies)),
+                message=(
+                    "ceilings in more than one currency cannot be summed, so "
+                    "cumulative analysis would be meaningless"
+                ),
+            )
+        )
+
+    order = {ERROR: 0, WARNING: 1}
+    return sorted(findings, key=lambda f: (order[f.severity], f.rule, f.subject))