agentguard-oss 0.4.1__py3-none-any.whl

agentguard/__init__.py

@@ -0,0 +1,41 @@
+"""AgentGuard's public SDK.
+
+Public API: the names in ``__all__`` here, plus ``agentguard.approval``,
+``agentguard.execution``, ``agentguard.adapters.*`` and
+``agentguard.risk.gemma_judge.GemmaJudge``. Other modules are internal and may change.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from agentguard.approval.base import Approval, ApprovalProvider
+from agentguard.core.action import Action
+from agentguard.core.decision import (
+    ApprovalPending,
+    Decision,
+    Effect,
+    GuardDenied,
+    GuardError,
+)
+from agentguard.core.guard import Guard
+from agentguard.policy.explain import explain
+from agentguard.policy.loader import load_policy
+
+try:
+    __version__ = version("agentguard-oss")
+except PackageNotFoundError:  # Running from a source tree without installation.
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "Action",
+    "Approval",
+    "ApprovalPending",
+    "ApprovalProvider",
+    "Decision",
+    "Effect",
+    "Guard",
+    "GuardDenied",
+    "GuardError",
+    "__version__",
+    "explain",
+    "load_policy",
+]

agentguard/__main__.py

@@ -0,0 +1,3 @@
+from agentguard.cli.main import main
+
+raise SystemExit(main())

agentguard/adapters/_common.py

@@ -0,0 +1,54 @@
+"""Shared adapter helpers. Adapters translate and dispatch; they make no security decisions."""
+
+import functools
+import inspect
+
+from agentguard.core.decision import ApprovalPending, GuardDenied
+
+
+def denial_result(exc: GuardDenied) -> dict:
+    """What the model sees when AgentGuard denies a call: the reasons, so it can adapt."""
+    if isinstance(exc, ApprovalPending):
+        return {
+            "error": "Approval pending",
+            "request_id": exc.request_id,
+            "reasons": list(exc.decision.reasons),
+            "next_step": "A human must approve this. Continue with other work and retry "
+            "the same call later.",
+        }
+    return {"error": "Denied by AgentGuard", "reasons": list(exc.decision.reasons)}
+
+
+def returning_denials(guarded, on_denied=denial_result):
+    """Wrap a guarded tool so denials become a result instead of an exception.
+
+    Only GuardDenied is converted. Other GuardErrors (a halted session, failed execution)
+    still raise, so frameworks surface them as tool failures.
+    """
+    if inspect.iscoroutinefunction(guarded):
+
+        @functools.wraps(guarded)
+        async def wrapper(*args, **kwargs):
+            try:
+                return await guarded(*args, **kwargs)
+            except GuardDenied as exc:
+                return on_denied(exc)
+    else:
+
+        @functools.wraps(guarded)
+        def wrapper(*args, **kwargs):
+            try:
+                return guarded(*args, **kwargs)
+            except GuardDenied as exc:
+                return on_denied(exc)
+
+    # The return type changes on denial; frameworks infer only the arguments from this.
+    wrapper.__signature__ = inspect.signature(guarded).replace(
+        return_annotation=inspect.Signature.empty
+    )
+    wrapper.__annotations__ = {k: v for k, v in guarded.__annotations__.items() if k != "return"}
+    return wrapper
+
+
+def describe(function, description):
+    return description or inspect.getdoc(function) or f"{function.__name__} (guarded by AgentGuard)"

agentguard/adapters/adk.py

@@ -0,0 +1,23 @@
+"""Google Agent Development Kit (ADK) tools backed by AgentGuard.
+
+Requires ``agentguard-oss[adk]``. Pass only the returned FunctionTool to ``Agent(tools=[...])``.
+ADK builds the declaration from the function's signature and docstring.
+"""
+
+from google.adk.tools import FunctionTool
+
+from agentguard.adapters._common import returning_denials
+
+
+def from_guarded(guarded, *, return_denials=True) -> FunctionTool:
+    """Wrap a function already decorated with ``@guard.tool``."""
+    return FunctionTool(returning_denials(guarded) if return_denials else guarded)
+
+
+def guarded_tool(guard, function, *, capability, name=None, return_denials=True, **options):
+    """Register ``function`` with ``guard`` and return it as an ADK FunctionTool.
+
+    ``options`` are passed to ``guard.tool`` (executor, verifier, path_arg, ...).
+    """
+    guarded = guard.tool(capability=capability, name=name, **options)(function)
+    return from_guarded(guarded, return_denials=return_denials)

agentguard/adapters/langchain.py

@@ -0,0 +1,31 @@
+"""LangChain and LangGraph tools backed by AgentGuard. Requires ``agentguard-oss[langchain]``.
+
+The returned StructuredTool works anywhere LangChain tools do, including LangGraph's
+ToolNode and prebuilt agents. Pass only the returned tool to the agent.
+"""
+
+import inspect
+
+from langchain_core.tools import StructuredTool
+
+from agentguard.adapters._common import describe, returning_denials
+
+
+def from_guarded(guarded, *, name=None, description=None, return_denials=True):
+    """Wrap a function already decorated with ``@guard.tool``."""
+    func = returning_denials(guarded) if return_denials else guarded
+    options = {"name": name or guarded.__name__, "description": describe(guarded, description)}
+    if inspect.iscoroutinefunction(guarded):
+        return StructuredTool.from_function(coroutine=func, **options)
+    return StructuredTool.from_function(func=func, **options)
+
+
+def guarded_tool(
+    guard, function, *, capability, name=None, description=None, return_denials=True, **options
+):
+    """Register ``function`` with ``guard`` and return it as a LangChain StructuredTool.
+
+    ``options`` are passed to ``guard.tool`` (executor, verifier, path_arg, ...).
+    """
+    guarded = guard.tool(capability=capability, name=name, **options)(function)
+    return from_guarded(guarded, description=description, return_denials=return_denials)

agentguard/adapters/mcp.py

@@ -0,0 +1,5 @@
+def register_tool(server, guard, function, *, capability, **options):
+    """Register a guarded callable on an MCP Python SDK 1.x FastMCP server."""
+    guarded = guard.tool(capability=capability, **options)(function)
+    server.add_tool(guarded)
+    return guarded

agentguard/adapters/openai_agents.py

@@ -0,0 +1,29 @@
+"""OpenAI Agents SDK tools backed by AgentGuard. Requires ``agentguard-oss[openai-agents]``.
+
+Pass only the returned FunctionTool to ``Agent(tools=[...])``.
+"""
+
+from agents import FunctionTool, function_tool
+
+from agentguard.adapters._common import describe, returning_denials
+
+
+def from_guarded(guarded, *, name=None, description=None, return_denials=True) -> FunctionTool:
+    """Wrap a function already decorated with ``@guard.tool``."""
+    func = returning_denials(guarded) if return_denials else guarded
+    return function_tool(
+        func,
+        name_override=name or guarded.__name__,
+        description_override=describe(guarded, description),
+    )
+
+
+def guarded_tool(
+    guard, function, *, capability, name=None, description=None, return_denials=True, **options
+) -> FunctionTool:
+    """Register ``function`` with ``guard`` and return it as an Agents SDK FunctionTool.
+
+    ``options`` are passed to ``guard.tool`` (executor, verifier, path_arg, ...).
+    """
+    guarded = guard.tool(capability=capability, name=name, **options)(function)
+    return from_guarded(guarded, description=description, return_denials=return_denials)

agentguard/adapters/python.py

@@ -0,0 +1,3 @@
+from agentguard.interceptors.middleware import GuardMiddleware
+
+__all__ = ["GuardMiddleware"]

agentguard/approval/__init__.py

@@ -0,0 +1,16 @@
+from agentguard.approval.base import Approval, ApprovalProvider
+from agentguard.approval.cli import CLIApproval
+from agentguard.approval.queue import QueueApproval
+from agentguard.approval.slack import SlackNotifier
+from agentguard.approval.store import ApprovalStore
+from agentguard.approval.webhook import WebhookNotifier
+
+__all__ = [
+    "Approval",
+    "ApprovalProvider",
+    "ApprovalStore",
+    "CLIApproval",
+    "QueueApproval",
+    "SlackNotifier",
+    "WebhookNotifier",
+]

agentguard/approval/base.py

@@ -0,0 +1,49 @@
+from dataclasses import dataclass
+from queue import Empty, Queue
+from threading import Thread
+from typing import Protocol
+
+from agentguard.core.action import Action
+from agentguard.core.decision import Decision
+
+
+@dataclass(frozen=True)
+class Approval:
+    approved: bool
+    approved_by: str = "unknown"
+    strong: bool = False
+    # Set when the request is queued for a human instead of answered now.
+    pending_id: str | None = None
+
+
+class ApprovalProvider(Protocol):
+    def request(self, action: Action, decision: Decision) -> Approval: ...
+
+
+def request_bounded(provider, action, decision, timeout: float) -> Approval:
+    """Late responses never authorize execution. Providers are trusted host code."""
+    queue = Queue(maxsize=1)
+
+    def request():
+        try:
+            queue.put(provider.request(action.model_copy(deep=True), decision))
+        except Exception:
+            queue.put(Approval(False))
+
+    Thread(target=request, daemon=True).start()
+    try:
+        answer = queue.get(timeout=timeout)
+        if not isinstance(answer, Approval) or type(answer.approved) is not bool:
+            return Approval(False)
+        if answer.pending_id is not None:
+            # Queued for a human: valid only as a non-approval carrying a request ID.
+            if answer.approved or not isinstance(answer.pending_id, str):
+                return Approval(False)
+            return Approval(False, pending_id=answer.pending_id)
+        if answer.approved and (not answer.approved_by or answer.approved_by == "unknown"):
+            return Approval(False)
+        if decision.strong_approval and answer.strong is not True:
+            return Approval(False)
+        return answer
+    except Empty:
+        return Approval(False)

agentguard/approval/cli.py

@@ -0,0 +1,47 @@
+import getpass
+import json
+import os
+import select
+import sys
+import threading
+import time
+
+from agentguard.approval.base import Approval
+from agentguard.risk.secrets import redact
+
+
+class CLIApproval:
+    """Approve one action using a terminal. No session-wide grants or reauthentication."""
+
+    def __init__(self, timeout: float = 30):
+        self.timeout = timeout
+        self._lock = threading.Lock()
+
+    def request(self, action, decision):
+        if not sys.stdin.isatty() or decision.strong_approval:
+            return Approval(False)
+        if not self._lock.acquire(blocking=False):
+            return Approval(False)
+        try:
+            print("\nAGENTGUARD APPROVAL REQUEST", file=sys.stderr)
+            print(json.dumps(redact(action.model_dump()), indent=2), file=sys.stderr)
+            print(f"Risk: {decision.risk_score}/100", file=sys.stderr)
+            print("; ".join(redact(list(decision.reasons))), file=sys.stderr)
+            print("[A] Approve once / [R] Reject: ", end="", file=sys.stderr, flush=True)
+            deadline = time.monotonic() + self.timeout
+            answer = ""
+            if os.name == "nt":
+                import msvcrt
+
+                while msvcrt.kbhit():
+                    msvcrt.getwch()
+                while time.monotonic() < deadline:
+                    if msvcrt.kbhit():
+                        answer = msvcrt.getwch().lower()
+                        break
+                    time.sleep(0.05)
+            elif select.select([sys.stdin], [], [], max(0, deadline - time.monotonic()))[0]:
+                answer = sys.stdin.readline().strip().lower()
+            return Approval(answer == "a", getpass.getuser())
+        finally:
+            self._lock.release()

agentguard/approval/queue.py

@@ -0,0 +1,90 @@
+"""Approval through a shared queue: dashboard, API, Slack or webhook approvers."""
+
+import asyncio
+import logging
+import threading
+import time
+
+from agentguard.approval.base import Approval
+from agentguard.approval.store import ApprovalStore
+
+log = logging.getLogger(__name__)
+
+
+class QueueApproval:
+    """Ask humans through an ApprovalStore without holding the agent hostage.
+
+    - An active grant for the call (approved earlier, or "allow this tool for 10 minutes")
+      approves immediately.
+    - Otherwise a request is queued (an identical pending call reuses it) and notifiers run.
+    - The provider waits up to ``wait`` seconds for a decision. If none arrives, the call
+      raises ``ApprovalPending`` with the request ID. Retrying the same call after approval
+      succeeds through the grant. ``wait=0`` (default) never blocks the agent.
+
+    Keep the Guard's ``approval_timeout`` above ``wait``.
+    """
+
+    def __init__(self, store, *, wait=0.0, request_ttl=3600.0, notifiers=(), poll_interval=0.25):
+        if wait < 0 or request_ttl <= 0:
+            raise ValueError("wait must be >= 0 and request_ttl > 0")
+        self.store = store if isinstance(store, ApprovalStore) else ApprovalStore(store)
+        self.timeout = wait
+        self.request_ttl = request_ttl
+        self.notifiers = tuple(notifiers)
+        self.poll_interval = poll_interval
+
+    def request(self, action, decision):
+        grant = self.store.use_grant(action, decision)
+        if grant:
+            return _granted(grant)
+        request, created = self.store.submit(action, decision, ttl=self.request_ttl)
+        if request["status"] == "rejected":
+            return Approval(False)  # The same call was recently rejected.
+        if created and self.notifiers:
+            threading.Thread(
+                target=self._notify, args=(request,), name="agentguard-notify", daemon=True
+            ).start()
+        deadline = time.monotonic() + self.timeout
+        while time.monotonic() < deadline:
+            status = (self.store.get(request["id"]) or {}).get("status")
+            if status == "approved":
+                grant = self.store.use_grant(action, decision)
+                return _granted(grant) if grant else Approval(False)
+            if status in {"rejected", "expired"}:
+                return Approval(False)
+            time.sleep(min(self.poll_interval, max(0.0, deadline - time.monotonic())))
+        return Approval(False, pending_id=request["id"])
+
+    def status(self, request_id):
+        """pending, approved, rejected or expired (None if unknown)."""
+        request = self.store.get(request_id)
+        return request["status"] if request else None
+
+    def wait_for(self, request_id, timeout):
+        """Block until the request is decided or ``timeout`` passes. Returns its status."""
+        deadline = time.monotonic() + timeout
+        while (status := self.status(request_id)) == "pending" and time.monotonic() < deadline:
+            time.sleep(self.poll_interval)
+        return status
+
+    async def await_decision(self, request_id, timeout):
+        """Async ``wait_for``: lets other tasks run while a human decides."""
+        deadline = time.monotonic() + timeout
+        while (status := self.status(request_id)) == "pending" and time.monotonic() < deadline:
+            await asyncio.sleep(self.poll_interval)
+        return status
+
+    def _notify(self, request):
+        for notifier in self.notifiers:
+            try:
+                notifier.notify(request)
+            except Exception:
+                log.warning("AgentGuard approval notifier %r failed", notifier, exc_info=True)
+
+
+def _granted(grant):
+    return Approval(
+        True,
+        approved_by=f"{grant['approved_by']} (grant {grant['id']})",
+        strong=bool(grant["strong"]),
+    )

agentguard/approval/slack.py

@@ -0,0 +1,174 @@
+"""Slack approvals: a message with buttons, and a verified handler for button clicks.
+
+Setup: create a Slack app with a bot token (``chat:write``), invite it to a channel, turn
+on Interactivity with the request URL ``<dashboard>/slack/actions``, and link approvers
+to Slack users (``agentguard approvers add NAME --slack-user U123``). The dashboard
+verifies Slack's signing secret on every click. Strong approval is never given in Slack.
+"""
+
+import hashlib
+import hmac
+import json
+import time
+from urllib.parse import parse_qs
+
+import httpx
+
+from agentguard.approval.webhook import summarize
+
+ACTIONS = {
+    "agentguard_approve_once": ("once", None),
+    "agentguard_allow_tool_10": ("tool", 10),
+    "agentguard_reject": (None, None),
+}
+
+
+def _text(summary):
+    reasons = "\n".join(f"• {reason}" for reason in summary["reasons"][:6]) or "• (none)"
+    arguments = json.dumps(summary["arguments"], sort_keys=True)
+    if len(arguments) > 600:
+        arguments = arguments[:600] + "…"
+    return (
+        f"*AgentGuard approval needed* (`{summary['id']}`)\n"
+        f"Agent `{summary['agent_id']}` wants `{summary['tool']}` "
+        f"({summary['capability']}) in {summary['environment']}. Risk {summary['risk']}/100.\n"
+        f"{reasons}\n```{arguments}```"
+    )
+
+
+def build_message(request, *, interactive=True, dashboard_url=None):
+    summary = summarize(request, dashboard_url)
+    blocks = [{"type": "section", "text": {"type": "mrkdwn", "text": _text(summary)}}]
+    buttons = []
+    if interactive and not summary["strong_required"]:
+        buttons = [
+            {
+                "type": "button",
+                "action_id": "agentguard_approve_once",
+                "text": {"type": "plain_text", "text": "Approve once"},
+                "style": "primary",
+                "value": summary["id"],
+            },
+            {
+                "type": "button",
+                "action_id": "agentguard_allow_tool_10",
+                "text": {"type": "plain_text", "text": "Allow this tool 10 min"},
+                "value": summary["id"],
+            },
+            {
+                "type": "button",
+                "action_id": "agentguard_reject",
+                "text": {"type": "plain_text", "text": "Reject"},
+                "style": "danger",
+                "value": summary["id"],
+            },
+        ]
+    if summary.get("review_url"):
+        buttons.append(
+            {
+                "type": "button",
+                "action_id": "agentguard_open",
+                "text": {"type": "plain_text", "text": "Open dashboard"},
+                "url": summary["review_url"],
+            }
+        )
+    if summary["strong_required"]:
+        blocks.append(
+            {
+                "type": "context",
+                "elements": [
+                    {"type": "mrkdwn", "text": "Strong approval required: use the dashboard."}
+                ],
+            }
+        )
+    if buttons:
+        blocks.append({"type": "actions", "elements": buttons})
+    fallback = f"AgentGuard approval needed: {summary['tool']} ({summary['id']})"
+    return {"text": fallback, "blocks": blocks}
+
+
+class SlackNotifier:
+    """Post approval requests to Slack.
+
+    With ``bot_token`` and ``channel``: interactive buttons (needs the dashboard's
+    ``/slack/actions`` endpoint). With ``webhook_url``: a message linking to the dashboard.
+    """
+
+    def __init__(
+        self,
+        *,
+        bot_token=None,
+        channel=None,
+        webhook_url=None,
+        dashboard_url=None,
+        timeout=5.0,
+        client=None,
+    ):
+        if not (bot_token and channel) and not webhook_url:
+            raise ValueError("Provide bot_token and channel, or webhook_url")
+        self.bot_token, self.channel, self.webhook_url = bot_token, channel, webhook_url
+        self.dashboard_url = dashboard_url
+        self.client = client or httpx.Client(timeout=timeout, trust_env=False)
+
+    def notify(self, request):
+        if self.bot_token:
+            message = build_message(request, interactive=True, dashboard_url=self.dashboard_url)
+            response = self.client.post(
+                "https://slack.com/api/chat.postMessage",
+                headers={"Authorization": f"Bearer {self.bot_token}"},
+                json={"channel": self.channel, **message},
+            )
+            response.raise_for_status()
+            if not response.json().get("ok"):
+                raise RuntimeError(f"Slack error: {response.json().get('error')}")
+        else:
+            message = build_message(request, interactive=False, dashboard_url=self.dashboard_url)
+            self.client.post(self.webhook_url, json=message).raise_for_status()
+
+
+def verify_slack_signature(signing_secret, timestamp, body, received, *, now=None):
+    """Slack's v0 request signature, rejecting requests older than five minutes."""
+    try:
+        if abs((now or time.time()) - int(timestamp)) > 300:
+            return False
+    except (TypeError, ValueError):
+        return False
+    secret = signing_secret.encode() if isinstance(signing_secret, str) else signing_secret
+    base = b"v0:" + timestamp.encode() + b":" + body
+    expected = "v0=" + hmac.new(secret, base, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, received or "")
+
+
+def handle_action(store, body: bytes):
+    """Apply a verified Slack button click. Returns the text to show in Slack."""
+    payload = json.loads(parse_qs(body.decode())["payload"][0])
+    user = payload.get("user", {}).get("id")
+    approver = store.approver_for_slack(user)
+    if approver is None:
+        return "You are not an AgentGuard approver."
+    action = (payload.get("actions") or [{}])[0]
+    if action.get("action_id") not in ACTIONS:
+        return "Unknown action."
+    scope, minutes = ACTIONS[action["action_id"]]
+    try:
+        request = store.resolve(
+            action.get("value"),
+            approved=scope is not None,
+            approver=approver["name"],
+            scope=scope or "once",
+            minutes=minutes,
+        )
+    except (KeyError, ValueError, PermissionError) as exc:
+        return f"Not applied: {exc}"
+    if request["status"] == "rejected":
+        return f"Rejected by {approver['name']}."
+    detail = "for this one call" if scope == "once" else f"for {request['tool']} for {minutes} min"
+    return f"Approved by {approver['name']} {detail}."
+
+
+def post_response(response_url, text, client=None):
+    """Replace the original Slack message with the outcome. Only Slack's own hook URLs."""
+    if not str(response_url).startswith("https://hooks.slack.com/"):
+        return
+    client = client or httpx.Client(timeout=5.0, trust_env=False)
+    client.post(response_url, json={"replace_original": True, "text": text})