agent_hypervisor 3.1.0__py3-none-any.whl

hypervisor/rings/breach_detector.py

@@ -0,0 +1,200 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Ring Breach Detector — behavioral anomaly detection for rogue agents.
+
+Detects two classes of anomaly:
+
+1. **Tool-call frequency spikes** — an agent's call rate inside a sliding
+   window exceeds a configurable baseline by a severity-dependent multiplier.
+2. **Privilege-escalation attempts** — a low-privilege agent (Ring 3)
+   repeatedly calls into higher-privilege rings (Ring 0/1).  The *ring
+   distance* amplifies the anomaly score so that sandbox→root jumps are
+   scored more aggressively than standard→privileged ones.
+
+When a HIGH or CRITICAL breach is detected the internal circuit-breaker
+trips and ``is_breaker_tripped()`` returns ``True`` until explicitly reset
+via ``reset_breaker()``.
+"""
+
+from __future__ import annotations
+
+import time
+from collections import deque
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import Enum
+
+from hypervisor.models import ExecutionRing
+
+
+class BreachSeverity(str, Enum):
+    NONE = "none"
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+
+# Multiplier thresholds: actual_rate / baseline_rate
+_SEVERITY_THRESHOLDS: list[tuple[float, BreachSeverity]] = [
+    (20.0, BreachSeverity.CRITICAL),
+    (10.0, BreachSeverity.HIGH),
+    (5.0, BreachSeverity.MEDIUM),
+    (2.0, BreachSeverity.LOW),
+]
+
+
+@dataclass
+class BreachEvent:
+    """A detected ring breach anomaly."""
+
+    agent_did: str
+    session_id: str
+    severity: BreachSeverity
+    anomaly_score: float
+    call_count_window: int
+    expected_rate: float
+    actual_rate: float
+    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
+    details: str = ""
+
+
+def _agent_key(agent_did: str, session_id: str) -> str:
+    """Internal composite key for per-agent tracking."""
+    return f"{agent_did}::{session_id}"
+
+
+class RingBreachDetector:
+    """Behavioural anomaly detector for rogue-agent ring abuse.
+
+    Parameters
+    ----------
+    window_seconds:
+        Sliding window (in seconds) over which call rates are measured.
+    baseline_rate:
+        Expected calls-per-second within the window.  Rates above multiples
+        of this value trigger breach events of increasing severity.
+    max_events_per_agent:
+        Maximum call timestamps retained per agent (bounded ``deque``).
+    """
+
+    def __init__(
+        self,
+        window_seconds: int = 60,
+        baseline_rate: float = 10.0,
+        max_events_per_agent: int = 1_000,
+        max_breach_history: int = 10_000,
+    ) -> None:
+        self.window_seconds = window_seconds
+        self.baseline_rate = baseline_rate
+        self.max_events_per_agent = max_events_per_agent
+
+        # Per-agent sliding-window timestamps
+        self._call_windows: dict[str, deque[float]] = {}
+        # Per-agent circuit-breaker flag
+        self._tripped: dict[str, bool] = {}
+        # Global breach history (bounded)
+        self._breach_history: deque[BreachEvent] = deque(maxlen=max_breach_history)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def record_call(
+        self,
+        agent_did: str,
+        session_id: str,
+        agent_ring: ExecutionRing,
+        called_ring: ExecutionRing,
+    ) -> BreachEvent | None:
+        """Record a ring call and return a ``BreachEvent`` if anomalous.
+
+        Returns ``None`` when the call is within normal parameters.
+        """
+        key = _agent_key(agent_did, session_id)
+        now = time.monotonic()
+
+        # --- 1. Track timestamp in bounded deque ---
+        if key not in self._call_windows:
+            self._call_windows[key] = deque(maxlen=self.max_events_per_agent)
+        window = self._call_windows[key]
+        window.append(now)
+
+        # --- 2. Prune timestamps outside the sliding window ---
+        cutoff = now - self.window_seconds
+        while window and window[0] < cutoff:
+            window.popleft()
+
+        # --- 3. Compute actual rate (calls / second) ---
+        call_count = len(window)
+        actual_rate = call_count / self.window_seconds if self.window_seconds > 0 else 0.0
+
+        # --- 4. Ring-distance amplifier ---
+        #   Upward calls (low value = higher privilege) are escalations.
+        #   ExecutionRing values: 0=root, 1=priv, 2=std, 3=sandbox.
+        #   ring_distance > 0 means privilege escalation.
+        ring_distance = int(agent_ring) - int(called_ring)
+        amplifier = max(ring_distance, 1)  # at least 1× (no reduction)
+
+        # --- 5. Score = (actual / baseline) × amplifier ---
+        if self.baseline_rate <= 0:
+            ratio = 0.0
+        else:
+            ratio = actual_rate / self.baseline_rate
+        anomaly_score = ratio * amplifier
+
+        # --- 6. Map score → severity ---
+        severity = BreachSeverity.NONE
+        for threshold, sev in _SEVERITY_THRESHOLDS:
+            if anomaly_score >= threshold:
+                severity = sev
+                break
+
+        if severity == BreachSeverity.NONE:
+            return None
+
+        # --- 7. Build event ---
+        event = BreachEvent(
+            agent_did=agent_did,
+            session_id=session_id,
+            severity=severity,
+            anomaly_score=round(anomaly_score, 4),
+            call_count_window=call_count,
+            expected_rate=self.baseline_rate,
+            actual_rate=round(actual_rate, 4),
+            details=(
+                f"rate={actual_rate:.2f}/s (baseline={self.baseline_rate:.2f}/s), "
+                f"ring_distance={ring_distance}, amplifier={amplifier}×, "
+                f"score={anomaly_score:.2f}"
+            ),
+        )
+        self._breach_history.append(event)
+
+        # --- 8. Trip circuit-breaker on HIGH / CRITICAL ---
+        if severity in (BreachSeverity.HIGH, BreachSeverity.CRITICAL):
+            self._tripped[key] = True
+
+        return event
+
+    def is_breaker_tripped(self, agent_did: str, session_id: str) -> bool:
+        """Return ``True`` if the circuit-breaker is tripped for this agent."""
+        return self._tripped.get(_agent_key(agent_did, session_id), False)
+
+    def reset_breaker(self, agent_did: str, session_id: str) -> None:
+        """Reset the circuit-breaker and clear the call window for this agent."""
+        key = _agent_key(agent_did, session_id)
+        self._tripped.pop(key, None)
+        self._call_windows.pop(key, None)
+
+    # ------------------------------------------------------------------
+    # Read-only accessors
+    # ------------------------------------------------------------------
+
+    @property
+    def breach_history(self) -> list[BreachEvent]:
+        return list(self._breach_history)
+
+    @property
+    def breach_count(self) -> int:
+        return len(self._breach_history)

hypervisor/rings/classifier.py

@@ -0,0 +1,78 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# Public Preview — basic implementation
+"""
+Action Risk Classifier
+
+Classifies actions into ring levels and risk weights.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from hypervisor.models import ActionDescriptor, ExecutionRing, ReversibilityLevel
+
+
+@dataclass
+class ClassificationResult:
+    """Result of classifying an action."""
+
+    action_id: str
+    ring: ExecutionRing
+    risk_weight: float
+    reversibility: ReversibilityLevel
+    confidence: float = 1.0
+
+
+class ActionClassifier:
+    """
+    Classifies actions into ring levels and risk weights.
+
+    Classification rules:
+    - Has Undo_API → reversible → Ring 2 minimum
+    - No Undo_API + destructive → non-reversible → Ring 1 minimum
+    - Config/admin operations → Ring 0
+    - Read-only operations → Ring 3
+    """
+
+    def __init__(self) -> None:
+        self._cache: dict[str, ClassificationResult] = {}
+        self._overrides: dict[str, ClassificationResult] = {}
+
+    def classify(self, action: ActionDescriptor) -> ClassificationResult:
+        """Classify an action and cache the result."""
+        if action.action_id in self._overrides:
+            return self._overrides[action.action_id]
+
+        if action.action_id in self._cache:
+            return self._cache[action.action_id]
+
+        result = ClassificationResult(
+            action_id=action.action_id,
+            ring=action.required_ring,
+            risk_weight=action.risk_weight,
+            reversibility=action.reversibility,
+        )
+        self._cache[action.action_id] = result
+        return result
+
+    def set_override(
+        self,
+        action_id: str,
+        ring: ExecutionRing | None = None,
+        risk_weight: float | None = None,
+    ) -> None:
+        """Set a session-level override for action classification."""
+        existing = self._cache.get(action_id)
+        self._overrides[action_id] = ClassificationResult(
+            action_id=action_id,
+            ring=ring or (existing.ring if existing else ExecutionRing.RING_3_SANDBOX),
+            risk_weight=risk_weight or (existing.risk_weight if existing else 0.5),
+            reversibility=existing.reversibility if existing else ReversibilityLevel.NONE,
+            confidence=0.9,  # overrides have slightly lower confidence
+        )
+
+    def clear_cache(self) -> None:
+        """Clear classification cache (e.g., on manifest update)."""
+        self._cache.clear()

hypervisor/rings/elevation.py

@@ -0,0 +1,219 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# Public Preview — basic implementation
+"""
+Ring Elevation — privilege escalation stubs.
+
+Public Preview: elevation is not supported. All requests are denied.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+
+from hypervisor.models import ExecutionRing
+
+
+class RingElevationError(Exception):
+    """Raised for invalid ring elevation requests."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        current_ring: ExecutionRing | None = None,
+        target_ring: ExecutionRing | None = None,
+        reason: str | None = None,
+        agent_did: str = "",
+    ) -> None:
+        super().__init__(message)
+        self.current_ring = current_ring
+        self.target_ring = target_ring
+        self.denial_reason = reason
+        self.agent_did = agent_did
+
+
+class ElevationDenialReason:
+    """Standard denial reasons for ring elevation failures."""
+
+    COMMUNITY_EDITION = "community_edition"
+    INVALID_TARGET = "invalid_target"
+    RING_0_FORBIDDEN = "ring_0_forbidden"
+    INSUFFICIENT_TRUST = "insufficient_trust"
+    NO_SPONSORSHIP = "no_sponsorship"
+    EXPIRED_TTL = "expired_ttl"
+
+
+_RING_LABELS: dict[ExecutionRing, str] = {
+    ExecutionRing.RING_0_ROOT: "Ring 0 (Root)",
+    ExecutionRing.RING_1_PRIVILEGED: "Ring 1 (Privileged)",
+    ExecutionRing.RING_2_STANDARD: "Ring 2 (Standard)",
+    ExecutionRing.RING_3_SANDBOX: "Ring 3 (Sandbox)",
+}
+
+_DOCS_URL = "https://github.com/microsoft/agent-governance-toolkit/blob/main/docs/rings.md"
+
+
+@dataclass
+class RingElevation:
+    """A ring elevation grant (stub in Public Preview)."""
+
+    elevation_id: str = field(default_factory=lambda: f"elev:{uuid.uuid4().hex[:8]}")
+    agent_did: str = ""
+    session_id: str = ""
+    original_ring: ExecutionRing = ExecutionRing.RING_3_SANDBOX
+    elevated_ring: ExecutionRing = ExecutionRing.RING_2_STANDARD
+    granted_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+    expires_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+    attestation: str | None = None
+    reason: str = ""
+    is_active: bool = True
+
+    @property
+    def is_expired(self) -> bool:
+        return True
+
+    @property
+    def remaining_seconds(self) -> float:
+        return 0.0
+
+
+class RingElevationManager:
+    """Manages ring elevations (Public Preview: always denies)."""
+
+    MAX_ELEVATION_TTL = 3600
+    DEFAULT_TTL = 300
+
+    def __init__(self) -> None:
+        self._elevations: dict[str, RingElevation] = {}
+
+    def request_elevation(
+        self,
+        agent_did: str,
+        session_id: str,
+        current_ring: ExecutionRing,
+        target_ring: ExecutionRing,
+        ttl_seconds: int = 0,
+        attestation: str | None = None,
+        reason: str = "",
+    ) -> RingElevation:
+        """Request temporary ring elevation (Public Preview: always denied)."""
+        # Validate: target must be a higher privilege (lower numeric value)
+        if target_ring.value >= current_ring.value:
+            denial = ElevationDenialReason.INVALID_TARGET
+            raise RingElevationError(
+                _build_elevation_error_message(
+                    current_ring=current_ring,
+                    target_ring=target_ring,
+                    reason=denial,
+                    agent_did=agent_did,
+                ),
+                current_ring=current_ring,
+                target_ring=target_ring,
+                reason=denial,
+                agent_did=agent_did,
+            )
+
+        # Validate: Ring 0 cannot be requested via standard API
+        if target_ring == ExecutionRing.RING_0_ROOT:
+            denial = ElevationDenialReason.RING_0_FORBIDDEN
+            raise RingElevationError(
+                _build_elevation_error_message(
+                    current_ring=current_ring,
+                    target_ring=target_ring,
+                    reason=denial,
+                    agent_did=agent_did,
+                ),
+                current_ring=current_ring,
+                target_ring=target_ring,
+                reason=denial,
+                agent_did=agent_did,
+            )
+
+        # Public Preview: all valid requests are denied
+        denial = ElevationDenialReason.COMMUNITY_EDITION
+        raise RingElevationError(
+            _build_elevation_error_message(
+                current_ring=current_ring,
+                target_ring=target_ring,
+                reason=denial,
+                agent_did=agent_did,
+            ),
+            current_ring=current_ring,
+            target_ring=target_ring,
+            reason=denial,
+            agent_did=agent_did,
+        )
+
+    def get_active_elevation(self, agent_did: str, session_id: str) -> RingElevation | None:
+        return None
+
+    def get_effective_ring(self, agent_did: str, session_id: str, base_ring: ExecutionRing) -> ExecutionRing:
+        return base_ring
+
+    def revoke_elevation(self, elevation_id: str) -> None:
+        raise RingElevationError(f"Elevation {elevation_id} not found")
+
+    def tick(self) -> list[RingElevation]:
+        return []
+
+    def register_child(self, parent_did: str, child_did: str, parent_ring: ExecutionRing) -> ExecutionRing:
+        child_ring_value = min(parent_ring.value + 1, ExecutionRing.RING_3_SANDBOX.value)
+        return ExecutionRing(child_ring_value)
+
+    @property
+    def active_elevations(self) -> list[RingElevation]:
+        return []
+
+
+_REMEDIATION: dict[str, str] = {
+    ElevationDenialReason.COMMUNITY_EDITION: (
+        "Upgrade to the Enterprise edition to enable ring elevation, "
+        "or request access from your organization admin."
+    ),
+    ElevationDenialReason.INVALID_TARGET: (
+        "Request a target ring with a lower numeric value (higher privilege) "
+        "than the agent's current ring."
+    ),
+    ElevationDenialReason.RING_0_FORBIDDEN: (
+        "Ring 0 requires SRE Witness attestation and cannot be requested "
+        "via the standard elevation API. Contact your platform team."
+    ),
+    ElevationDenialReason.INSUFFICIENT_TRUST: (
+        "Increase the agent's effective trust score above the required "
+        "threshold by completing successful operations in the current ring."
+    ),
+    ElevationDenialReason.NO_SPONSORSHIP: (
+        "Obtain a sponsorship from a Ring 1 or Ring 0 agent to vouch "
+        "for this elevation request."
+    ),
+    ElevationDenialReason.EXPIRED_TTL: (
+        "Submit a new elevation request with a valid TTL "
+        f"(max {RingElevationManager.MAX_ELEVATION_TTL}s)."
+    ),
+}
+
+
+def _build_elevation_error_message(
+    *,
+    current_ring: ExecutionRing,
+    target_ring: ExecutionRing,
+    reason: str,
+    agent_did: str = "",
+) -> str:
+    """Build a structured, actionable error message for elevation failures."""
+    current_label = _RING_LABELS.get(current_ring, str(current_ring))
+    target_label = _RING_LABELS.get(target_ring, str(target_ring))
+    remediation = _REMEDIATION.get(reason, "Review the elevation requirements.")
+
+    parts = [
+        f"Ring elevation denied: {current_label} -> {target_label}",
+    ]
+    if agent_did:
+        parts.append(f"  Agent: {agent_did}")
+    parts.append(f"  Reason: {reason}")
+    parts.append(f"  Remediation: {remediation}")
+    parts.append(f"  Docs: {_DOCS_URL}")
+    return "\n".join(parts)

hypervisor/rings/enforcer.py

@@ -0,0 +1,97 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# Public Preview — basic implementation
+"""
+Ring Enforcer — simple 2-tier access control.
+
+Public Preview: agents get RING_1 (trust > 0.7) or RING_2 (default).
+Ring 0 is reserved for kernel-only operations and always denied.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from hypervisor.constants import RING_1_ENFORCER_THRESHOLD
+from hypervisor.models import ActionDescriptor, ExecutionRing
+
+
+@dataclass
+class RingCheckResult:
+    """Result of a ring enforcement check."""
+
+    allowed: bool
+    required_ring: ExecutionRing
+    agent_ring: ExecutionRing
+    eff_score: float
+    reason: str
+    requires_consensus: bool = False
+    requires_sre_witness: bool = False
+
+
+class RingEnforcer:
+    """
+    Simple 2-tier ring enforcer.
+
+    Ring 0 (Root): Always denied (kernel-only).
+    Ring 1 (Privileged): Requires trust > 0.7.
+    Ring 2 (Standard): Default for all agents.
+    Ring 3 (Sandbox): Read-only / research.
+    """
+
+    RING_1_THRESHOLD = RING_1_ENFORCER_THRESHOLD
+
+    def __init__(self) -> None:
+        pass
+
+    def check(
+        self,
+        agent_ring: ExecutionRing,
+        action: ActionDescriptor,
+        eff_score: float,
+        has_consensus: bool = False,
+        has_sre_witness: bool = False,
+    ) -> RingCheckResult:
+        """Check if an agent can perform an action given their ring level."""
+        required = action.required_ring
+
+        # Ring 0: always denied in Public Preview
+        if required == ExecutionRing.RING_0_ROOT:
+            return RingCheckResult(
+                allowed=False,
+                required_ring=required,
+                agent_ring=agent_ring,
+                eff_score=eff_score,
+                reason="Ring 0 actions are not available in Public Preview",
+                requires_sre_witness=True,
+            )
+
+        # Agent's ring must be <= required ring (lower number = more privileged)
+        if agent_ring.value > required.value:
+            return RingCheckResult(
+                allowed=False,
+                required_ring=required,
+                agent_ring=agent_ring,
+                eff_score=eff_score,
+                reason=(
+                    f"Agent ring {agent_ring.value} insufficient for "
+                    f"required ring {required.value}"
+                ),
+            )
+
+        return RingCheckResult(
+            allowed=True,
+            required_ring=required,
+            agent_ring=agent_ring,
+            eff_score=eff_score,
+            reason="Access granted",
+        )
+
+    def compute_ring(self, eff_score: float, has_consensus: bool = False) -> ExecutionRing:
+        """Compute ring assignment from trust score."""
+        return ExecutionRing.from_eff_score(eff_score, has_consensus)
+
+    def should_demote(self, current_ring: ExecutionRing, eff_score: float) -> bool:
+        """Check if an agent should be demoted based on trust drop."""
+        appropriate = self.compute_ring(eff_score)
+        return appropriate.value > current_ring.value

hypervisor/saga/__init__.py

@@ -0,0 +1,22 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""Saga subpackage — orchestration, fan-out, checkpoints, DSL."""
+
+from hypervisor.saga.checkpoint import CheckpointManager, SemanticCheckpoint
+from hypervisor.saga.dsl import SagaDefinition, SagaDSLError, SagaDSLParser
+from hypervisor.saga.fan_out import FanOutGroup, FanOutOrchestrator, FanOutPolicy
+from hypervisor.saga.schema import SAGA_DEFINITION_SCHEMA, SagaSchemaError, SagaSchemaValidator
+
+__all__ = [
+    "FanOutOrchestrator",
+    "FanOutGroup",
+    "FanOutPolicy",
+    "CheckpointManager",
+    "SemanticCheckpoint",
+    "SagaDSLParser",
+    "SagaDefinition",
+    "SagaDSLError",
+    "SagaSchemaValidator",
+    "SagaSchemaError",
+    "SAGA_DEFINITION_SCHEMA",
+]