agent_os_kernel 3.1.0__py3-none-any.whl

agent_os/policies/evaluator.py

@@ -0,0 +1,239 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Standalone policy evaluator for Agent-OS governance.
+
+Evaluates declarative PolicyDocuments against an execution context dict,
+returning a PolicyDecision with matched rule, action, and audit information.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from .schema import PolicyAction, PolicyDocument, PolicyOperator, PolicyRule
+
+logger = logging.getLogger(__name__)
+
+
+class PolicyDecision(BaseModel):
+    """Result of evaluating policies against an execution context."""
+
+    allowed: bool = True
+    matched_rule: str | None = None
+    action: str = "allow"
+    reason: str = "No rules matched; default action applied"
+    audit_entry: dict[str, Any] = Field(default_factory=dict)
+
+
+class PolicyEvaluator:
+    """Evaluates a set of PolicyDocuments against execution contexts.
+
+    Supports external policy backends (OPA/Rego, Cedar) alongside the
+    native YAML/JSON engine. YAML rules are evaluated first; if no YAML
+    rule matches, external backends are consulted in registration order.
+    """
+
+    def __init__(self, policies: list[PolicyDocument] | None = None) -> None:
+        self.policies: list[PolicyDocument] = policies or []
+        self._backends: list[Any] = []
+
+    def load_policies(self, directory: str | Path) -> None:
+        """Load all YAML policy files from a directory."""
+        directory = Path(directory)
+        for path in sorted(directory.glob("*.yaml")):
+            self.policies.append(PolicyDocument.from_yaml(path))
+        for path in sorted(directory.glob("*.yml")):
+            self.policies.append(PolicyDocument.from_yaml(path))
+
+    def add_backend(self, backend: Any) -> None:
+        """Register an external policy backend (OPA, Cedar, etc.).
+
+        Backends are consulted in registration order when no YAML rule
+        matches. Each backend must implement ``evaluate(context) ->
+        BackendDecision`` and a ``name`` property.
+
+        Args:
+            backend: An ``ExternalPolicyBackend`` implementation such as
+                ``OPABackend`` or ``CedarBackend`` from
+                ``agent_os.policies.backends``.
+        """
+        self._backends.append(backend)
+
+    def load_rego(
+        self,
+        rego_path: str | None = None,
+        rego_content: str | None = None,
+        package: str = "agentos",
+    ) -> Any:
+        """Convenience: register an OPA/Rego backend.
+
+        Args:
+            rego_path: Path to a ``.rego`` file.
+            rego_content: Inline Rego policy string.
+            package: Rego package name for query construction.
+
+        Returns:
+            The ``OPABackend`` instance.
+        """
+        from .backends import OPABackend
+
+        backend = OPABackend(
+            rego_path=rego_path, rego_content=rego_content, package=package
+        )
+        self.add_backend(backend)
+        return backend
+
+    def load_cedar(
+        self,
+        policy_path: str | None = None,
+        policy_content: str | None = None,
+        entities: list[dict[str, Any]] | None = None,
+    ) -> Any:
+        """Convenience: register a Cedar backend.
+
+        Args:
+            policy_path: Path to a ``.cedar`` policy file.
+            policy_content: Inline Cedar policy string.
+            entities: Cedar entities for authorization context.
+
+        Returns:
+            The ``CedarBackend`` instance.
+        """
+        from .backends import CedarBackend
+
+        backend = CedarBackend(
+            policy_path=policy_path,
+            policy_content=policy_content,
+            entities=entities,
+        )
+        self.add_backend(backend)
+        return backend
+
+    def evaluate(self, context: dict[str, Any]) -> PolicyDecision:
+        """Evaluate all loaded policy rules against the given context.
+
+        Rules are sorted by priority (descending). The first matching rule
+        determines the decision. If no YAML rule matches and external
+        backends are registered, they are consulted in order. If nothing
+        matches, the default action from the first policy (or global allow)
+        is used.
+        """
+        try:
+            all_rules: list[tuple[PolicyRule, PolicyDocument]] = []
+            for doc in self.policies:
+                for rule in doc.rules:
+                    all_rules.append((rule, doc))
+
+            # Sort by priority descending so highest priority is checked first
+            all_rules.sort(key=lambda pair: pair[0].priority, reverse=True)
+
+            for rule, doc in all_rules:
+                if _match_condition(rule.condition, context):
+                    allowed = rule.action in (PolicyAction.ALLOW, PolicyAction.AUDIT)
+                    return PolicyDecision(
+                        allowed=allowed,
+                        matched_rule=rule.name,
+                        action=rule.action.value,
+                        reason=rule.message or f"Matched rule '{rule.name}'",
+                        audit_entry={
+                            "policy": doc.name,
+                            "rule": rule.name,
+                            "action": rule.action.value,
+                            "context_snapshot": context,
+                            "timestamp": datetime.now(timezone.utc).isoformat(),
+                        },
+                    )
+
+            # No YAML rule matched — consult external backends
+            for backend in self._backends:
+                result = backend.evaluate(context)
+                if result.error is None:
+                    return PolicyDecision(
+                        allowed=result.allowed,
+                        matched_rule=None,
+                        action=result.action,
+                        reason=result.reason,
+                        audit_entry={
+                            "policy": f"external:{backend.name}",
+                            "rule": None,
+                            "action": result.action,
+                            "backend": backend.name,
+                            "evaluation_ms": result.evaluation_ms,
+                            "context_snapshot": context,
+                            "timestamp": datetime.now(timezone.utc).isoformat(),
+                        },
+                    )
+
+            # No rule matched — apply defaults
+            default_action = PolicyAction.ALLOW
+            if self.policies:
+                default_action = self.policies[0].defaults.action
+            allowed = default_action in (PolicyAction.ALLOW, PolicyAction.AUDIT)
+            return PolicyDecision(
+                allowed=allowed,
+                action=default_action.value,
+                reason="No rules matched; default action applied",
+                audit_entry={
+                    "policy": self.policies[0].name if self.policies else None,
+                    "rule": None,
+                    "action": default_action.value,
+                    "context_snapshot": context,
+                    "timestamp": datetime.now(timezone.utc).isoformat(),
+                },
+            )
+        except Exception:
+            logger.error(
+                "Policy evaluation error — denying access (fail closed)",
+                exc_info=True,
+            )
+            return PolicyDecision(
+                allowed=False,
+                action="deny",
+                reason="Policy evaluation error — access denied (fail closed)",
+                audit_entry={
+                    "policy": None,
+                    "rule": None,
+                    "action": "deny",
+                    "context_snapshot": context,
+                    "timestamp": datetime.now(timezone.utc).isoformat(),
+                    "error": True,
+                },
+            )
+
+
+def _match_condition(condition: Any, context: dict[str, Any]) -> bool:
+    """Check whether a single PolicyCondition matches the context."""
+    ctx_value = context.get(condition.field)
+    if ctx_value is None:
+        return False
+
+    op = condition.operator
+    target = condition.value
+
+    if op == PolicyOperator.EQ:
+        return ctx_value == target
+    if op == PolicyOperator.NE:
+        return ctx_value != target
+    if op == PolicyOperator.GT:
+        return ctx_value > target
+    if op == PolicyOperator.LT:
+        return ctx_value < target
+    if op == PolicyOperator.GTE:
+        return ctx_value >= target
+    if op == PolicyOperator.LTE:
+        return ctx_value <= target
+    if op == PolicyOperator.IN:
+        return ctx_value in target
+    if op == PolicyOperator.CONTAINS:
+        return target in ctx_value
+    if op == PolicyOperator.MATCHES:
+        return bool(re.search(str(target), str(ctx_value)))
+
+    return False

agent_os/policies/policy_schema.json

@@ -0,0 +1,228 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/microsoft/agent-governance-toolkit/policy-schema/v1.0",
+  "title": "Agent-OS Policy Document",
+  "description": "JSON Schema for Agent-OS declarative governance policy documents.",
+  "type": "object",
+  "properties": {
+    "version": {
+      "type": "string",
+      "description": "Schema version identifier.",
+      "default": "1.0"
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable policy name.",
+      "default": "unnamed"
+    },
+    "description": {
+      "type": "string",
+      "description": "Detailed description of the policy purpose.",
+      "default": ""
+    },
+    "rules": {
+      "type": "array",
+      "description": "Ordered list of governance rules.",
+      "items": {
+        "$ref": "#/definitions/PolicyRule"
+      },
+      "default": []
+    },
+    "defaults": {
+      "$ref": "#/definitions/PolicyDefaults",
+      "description": "Default settings applied when no rule matches."
+    },
+    "a2a_conversation_policy": {
+      "$ref": "#/definitions/A2AConversationPolicy",
+      "description": "Policy for A2A conversation monitoring and feedback loop prevention."
+    }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "PolicyOperator": {
+      "type": "string",
+      "description": "Comparison operator for policy conditions.",
+      "enum": ["eq", "ne", "gt", "lt", "gte", "lte", "in", "matches", "contains"]
+    },
+    "PolicyAction": {
+      "type": "string",
+      "description": "Action a policy rule prescribes.",
+      "enum": ["allow", "deny", "audit", "block"]
+    },
+    "PolicyCondition": {
+      "type": "object",
+      "description": "A single condition evaluated against execution context.",
+      "properties": {
+        "field": {
+          "type": "string",
+          "description": "Context field name, e.g. 'tool_name', 'token_count'."
+        },
+        "operator": {
+          "$ref": "#/definitions/PolicyOperator",
+          "description": "Comparison operator."
+        },
+        "value": {
+          "description": "Value to compare against. Type depends on the operator."
+        }
+      },
+      "required": ["field", "operator", "value"],
+      "additionalProperties": false
+    },
+    "PolicyRule": {
+      "type": "object",
+      "description": "A single governance rule within a policy document.",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Unique rule identifier."
+        },
+        "condition": {
+          "$ref": "#/definitions/PolicyCondition",
+          "description": "Condition that triggers this rule."
+        },
+        "action": {
+          "$ref": "#/definitions/PolicyAction",
+          "description": "Action to take when the condition matches."
+        },
+        "priority": {
+          "type": "integer",
+          "description": "Higher priority rules are evaluated first.",
+          "default": 0
+        },
+        "message": {
+          "type": "string",
+          "description": "Human-readable explanation of the rule.",
+          "default": ""
+        }
+      },
+      "required": ["name", "condition", "action"],
+      "additionalProperties": false
+    },
+    "PolicyDefaults": {
+      "type": "object",
+      "description": "Default settings applied when no rule matches.",
+      "properties": {
+        "action": {
+          "$ref": "#/definitions/PolicyAction",
+          "description": "Default action when no rule matches.",
+          "default": "allow"
+        },
+        "max_tokens": {
+          "type": "integer",
+          "description": "Maximum token budget.",
+          "default": 4096
+        },
+        "max_tool_calls": {
+          "type": "integer",
+          "description": "Maximum number of tool calls allowed.",
+          "default": 10
+        },
+        "confidence_threshold": {
+          "type": "number",
+          "description": "Minimum confidence score required.",
+          "default": 0.8,
+          "minimum": 0.0,
+          "maximum": 1.0
+        }
+      },
+      "additionalProperties": false
+    },
+    "A2AConversationPolicy": {
+      "type": "object",
+      "description": "Policy for monitoring agent-to-agent conversations (OWASP ASI-8/10).",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Enable conversation guardian on A2A messages.",
+          "default": true
+        },
+        "escalation_score_threshold": {
+          "type": "number",
+          "description": "Escalation score that triggers PAUSE action.",
+          "default": 0.6,
+          "minimum": 0.0,
+          "maximum": 1.0
+        },
+        "escalation_warn_threshold": {
+          "type": "number",
+          "description": "Escalation score that triggers WARN action.",
+          "default": 0.4,
+          "minimum": 0.0,
+          "maximum": 1.0
+        },
+        "offensive_score_threshold": {
+          "type": "number",
+          "description": "Offensive intent score that triggers PAUSE action.",
+          "default": 0.5,
+          "minimum": 0.0,
+          "maximum": 1.0
+        },
+        "offensive_critical_threshold": {
+          "type": "number",
+          "description": "Offensive intent score that triggers QUARANTINE action.",
+          "default": 0.8,
+          "minimum": 0.0,
+          "maximum": 1.0
+        },
+        "max_retry_cycles": {
+          "type": "integer",
+          "description": "Max error-retry cycles before BREAK.",
+          "default": 3,
+          "minimum": 1
+        },
+        "max_conversation_turns": {
+          "type": "integer",
+          "description": "Max turns in a conversation before BREAK.",
+          "default": 30,
+          "minimum": 1
+        },
+        "on_escalation_detected": {
+          "type": "string",
+          "description": "Action when escalation is detected.",
+          "enum": ["warn", "pause", "break", "quarantine"],
+          "default": "warn"
+        },
+        "on_offensive_detected": {
+          "type": "string",
+          "description": "Action when offensive intent is detected.",
+          "enum": ["warn", "pause", "break", "quarantine"],
+          "default": "break"
+        },
+        "on_feedback_loop": {
+          "type": "string",
+          "description": "Action when feedback loop is detected.",
+          "enum": ["warn", "pause", "break", "quarantine"],
+          "default": "break"
+        },
+        "require_human_approval_on": {
+          "type": "array",
+          "description": "Conditions requiring human approval before proceeding.",
+          "items": {
+            "type": "string",
+            "enum": ["escalation_above_threshold", "offensive_intent_detected", "feedback_loop_detected"]
+          },
+          "default": []
+        },
+        "audit": {
+          "type": "object",
+          "description": "Audit settings for conversation monitoring.",
+          "properties": {
+            "capture_full_transcript": {
+              "type": "boolean",
+              "description": "Log full message content in audit trail.",
+              "default": true
+            },
+            "retention_days": {
+              "type": "integer",
+              "description": "Days to retain conversation audit logs. EU AI Act Art. 26(6) requires minimum 180 days for high-risk systems.",
+              "default": 180,
+              "minimum": 30
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

agent_os/policies/rate_limiting.py

@@ -0,0 +1,145 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""Shared rate limiting primitives for toolkit policy layers.
+
+These primitives provide a canonical token-bucket foundation without collapsing
+layer-specific limiters that serve different architectural boundaries.
+
+See also:
+    - hypervisor.security.rate_limiter: runtime-layer per-agent/per-ring limits.
+    - agent_os.integrations.rate_limiter: tool-call policy limits in Agent OS.
+    - agentmesh.services.rate_limiter: service/proxy-level limits in Agent Mesh.
+    - agentmesh.services.rate_limit_middleware: HTTP edge middleware in Agent Mesh.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+
+class RateLimitExceeded(Exception):
+    """Raised when a rate-limited operation cannot proceed."""
+
+
+@dataclass(frozen=True)
+class RateLimitConfig:
+    """Basic token-bucket configuration.
+
+    Args:
+        capacity: Maximum burst size (the most tokens the bucket may hold).
+        refill_rate: Tokens replenished per second.
+        initial_tokens: Optional initial token count. Defaults to ``capacity``.
+    """
+
+    capacity: float
+    refill_rate: float
+    initial_tokens: float | None = None
+
+    def __post_init__(self) -> None:
+        if self.capacity <= 0:
+            raise ValueError("capacity must be positive")
+        if self.refill_rate < 0:
+            raise ValueError("refill_rate must be non-negative")
+        if self.initial_tokens is not None and not 0 <= self.initial_tokens <= self.capacity:
+            raise ValueError(
+                "initial_tokens must be between 0 and capacity"
+            )
+
+    @property
+    def rate(self) -> float:
+        """Alias for ``refill_rate`` for callers that prefer ``rate`` terminology."""
+        return self.refill_rate
+
+
+@dataclass
+class TokenBucket:
+    """Thread-safe token bucket for rate limiting."""
+
+    capacity: float
+    tokens: float
+    refill_rate: float
+    last_refill: float = field(default_factory=time.monotonic)
+    _lock: Any = field(
+        default_factory=threading.Lock,
+        init=False,
+        repr=False,
+        compare=False,
+    )
+
+    def __post_init__(self) -> None:
+        if self.capacity <= 0:
+            raise ValueError("capacity must be positive")
+        if self.refill_rate < 0:
+            raise ValueError("refill_rate must be non-negative")
+        if not 0 <= self.tokens <= self.capacity:
+            raise ValueError("tokens must be between 0 and capacity")
+
+    @classmethod
+    def from_config(cls, config: RateLimitConfig) -> "TokenBucket":
+        """Build a token bucket from a :class:`RateLimitConfig`."""
+        initial_tokens = (
+            config.capacity if config.initial_tokens is None else config.initial_tokens
+        )
+        return cls(
+            capacity=config.capacity,
+            tokens=initial_tokens,
+            refill_rate=config.refill_rate,
+        )
+
+    def _refill_unlocked(self, now: float | None = None) -> None:
+        current = time.monotonic() if now is None else now
+        elapsed = current - self.last_refill
+        if elapsed <= 0:
+            return
+        self.tokens = min(self.capacity, self.tokens + elapsed * self.refill_rate)
+        self.last_refill = current
+
+    def consume(self, tokens: float = 1.0) -> bool:
+        """Try to consume *tokens*. Returns ``True`` when enough tokens exist."""
+        if tokens <= 0:
+            raise ValueError("tokens must be positive")
+        with self._lock:
+            self._refill_unlocked()
+            if self.tokens >= tokens:
+                self.tokens -= tokens
+                return True
+            return False
+
+    @property
+    def available(self) -> float:
+        """Current token count after refilling for elapsed time."""
+        with self._lock:
+            self._refill_unlocked()
+            return self.tokens
+
+    def tokens_available(self) -> float:
+        """Method alias for callers that prefer a function over a property."""
+        return self.available
+
+    def time_until_available(self, tokens: float = 1.0) -> float:
+        """Return seconds until *tokens* are available."""
+        if tokens <= 0:
+            raise ValueError("tokens must be positive")
+        with self._lock:
+            self._refill_unlocked()
+            if self.tokens >= tokens:
+                return 0.0
+            if self.refill_rate == 0:
+                return float("inf")
+            deficit = tokens - self.tokens
+            return deficit / self.refill_rate
+
+    def reset(self, tokens: float | None = None) -> None:
+        """Reset the bucket to *tokens* or back to full capacity."""
+        target_tokens = self.capacity if tokens is None else tokens
+        if not 0 <= target_tokens <= self.capacity:
+            raise ValueError("tokens must be between 0 and capacity")
+        with self._lock:
+            self.tokens = target_tokens
+            self.last_refill = time.monotonic()
+
+
+__all__ = ["RateLimitConfig", "RateLimitExceeded", "TokenBucket"]