agentmesh-platform 1.0.0a1__py3-none-any.whl

agentmesh/governance/policy.py

@@ -0,0 +1,385 @@
+"""
+Policy Engine
+
+Declarative policy engine with YAML/JSON policies.
+Policy evaluation latency <5ms with 100% deterministic results.
+"""
+
+from datetime import datetime
+from typing import Optional, Literal, Any, Callable
+from pydantic import BaseModel, Field
+import yaml
+import json
+import re
+
+
+class PolicyRule(BaseModel):
+    """
+    A single policy rule.
+    
+    Rules define conditions and actions:
+    - condition: Expression that evaluates to true/false
+    - action: What to do when condition matches (allow, deny, warn, require_approval)
+    """
+    
+    name: str = Field(..., description="Rule name")
+    description: Optional[str] = Field(None)
+    
+    # Condition
+    condition: str = Field(..., description="Condition expression")
+    
+    # Action
+    action: Literal["allow", "deny", "warn", "require_approval", "log"] = Field(
+        default="deny"
+    )
+    
+    # Rate limiting
+    limit: Optional[str] = Field(None, description="Rate limit (e.g., '100/hour')")
+    
+    # Approval workflow
+    approvers: list[str] = Field(default_factory=list)
+    
+    # Priority (higher = evaluated first)
+    priority: int = Field(default=0)
+    
+    # Enabled
+    enabled: bool = Field(default=True)
+    
+    def evaluate(self, context: dict) -> bool:
+        """
+        Evaluate the condition against a context.
+        
+        Supports simple expressions like:
+        - action.type == 'export'
+        - data.contains_pii
+        - user.role in ['admin', 'operator']
+        """
+        if not self.enabled:
+            return False
+        
+        try:
+            # Simple expression evaluation
+            # In production, would use a proper expression parser
+            return self._eval_expression(self.condition, context)
+        except Exception:
+            return False
+    
+    def _eval_expression(self, expr: str, context: dict) -> bool:
+        """Evaluate a simple expression."""
+        # Handle common patterns
+        
+        # Equality: action.type == 'export'
+        eq_match = re.match(r"(\w+(?:\.\w+)*)\s*==\s*['\"]([^'\"]+)['\"]", expr)
+        if eq_match:
+            path, value = eq_match.groups()
+            actual = self._get_nested(context, path)
+            return actual == value
+        
+        # Boolean attribute: data.contains_pii
+        bool_match = re.match(r"^(\w+(?:\.\w+)*)$", expr)
+        if bool_match:
+            path = bool_match.group(1)
+            return bool(self._get_nested(context, path))
+        
+        # AND conditions
+        if " and " in expr:
+            parts = expr.split(" and ")
+            return all(self._eval_expression(p.strip(), context) for p in parts)
+        
+        # OR conditions
+        if " or " in expr:
+            parts = expr.split(" or ")
+            return any(self._eval_expression(p.strip(), context) for p in parts)
+        
+        return False
+    
+    def _get_nested(self, obj: dict, path: str) -> Any:
+        """Get nested value from dict using dot notation."""
+        parts = path.split(".")
+        current = obj
+        for part in parts:
+            if isinstance(current, dict):
+                current = current.get(part)
+            else:
+                return None
+        return current
+
+
+class Policy(BaseModel):
+    """
+    Complete policy document.
+    
+    Policies are defined in YAML/JSON and loaded at runtime.
+    """
+    
+    version: str = Field(default="1.0")
+    name: str = Field(...)
+    description: Optional[str] = Field(None)
+    
+    # Target
+    agent: Optional[str] = Field(None, description="Agent this policy applies to")
+    agents: list[str] = Field(default_factory=list, description="Multiple agents")
+    
+    # Rules
+    rules: list[PolicyRule] = Field(default_factory=list)
+    
+    # Default action
+    default_action: Literal["allow", "deny"] = Field(default="deny")
+    
+    # Metadata
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: datetime = Field(default_factory=datetime.utcnow)
+    
+    @classmethod
+    def from_yaml(cls, yaml_content: str) -> "Policy":
+        """Load policy from YAML."""
+        data = yaml.safe_load(yaml_content)
+        
+        # Parse rules
+        rules = []
+        for rule_data in data.get("rules", []):
+            rules.append(PolicyRule(**rule_data))
+        data["rules"] = rules
+        
+        return cls(**data)
+    
+    @classmethod
+    def from_json(cls, json_content: str) -> "Policy":
+        """Load policy from JSON."""
+        data = json.loads(json_content)
+        
+        rules = []
+        for rule_data in data.get("rules", []):
+            rules.append(PolicyRule(**rule_data))
+        data["rules"] = rules
+        
+        return cls(**data)
+    
+    def applies_to(self, agent_did: str) -> bool:
+        """Check if this policy applies to an agent."""
+        if self.agent and self.agent == agent_did:
+            return True
+        if agent_did in self.agents:
+            return True
+        if "*" in self.agents:
+            return True
+        return False
+    
+    def to_yaml(self) -> str:
+        """Export policy as YAML."""
+        data = self.model_dump(exclude_none=True)
+        # Convert rules to dicts
+        data["rules"] = [r.model_dump(exclude_none=True) for r in self.rules]
+        return yaml.dump(data, default_flow_style=False)
+
+
+class PolicyDecision(BaseModel):
+    """Result of policy evaluation."""
+    
+    allowed: bool
+    action: Literal["allow", "deny", "warn", "require_approval", "log"]
+    
+    # Which rule matched
+    matched_rule: Optional[str] = None
+    policy_name: Optional[str] = None
+    
+    # Details
+    reason: Optional[str] = None
+    
+    # For require_approval
+    approvers: list[str] = Field(default_factory=list)
+    
+    # For rate limiting
+    rate_limited: bool = False
+    rate_limit_reset: Optional[datetime] = None
+    
+    # Timing
+    evaluated_at: datetime = Field(default_factory=datetime.utcnow)
+    evaluation_ms: Optional[float] = None
+
+
+class PolicyEngine:
+    """
+    Declarative policy engine.
+    
+    Features:
+    - YAML/JSON policy definitions
+    - <5ms evaluation latency
+    - 100% deterministic across runs
+    - Rate limiting support
+    - Approval workflows
+    """
+    
+    MAX_EVAL_MS = 5  # Target: <5ms evaluation
+    
+    def __init__(self):
+        self._policies: dict[str, Policy] = {}
+        self._rate_limits: dict[str, dict] = {}  # rule_name -> {count, reset_at}
+    
+    def load_policy(self, policy: Policy) -> None:
+        """Load a policy into the engine."""
+        self._policies[policy.name] = policy
+    
+    def load_yaml(self, yaml_content: str) -> Policy:
+        """Load policy from YAML string."""
+        policy = Policy.from_yaml(yaml_content)
+        self.load_policy(policy)
+        return policy
+    
+    def load_json(self, json_content: str) -> Policy:
+        """Load policy from JSON string."""
+        policy = Policy.from_json(json_content)
+        self.load_policy(policy)
+        return policy
+    
+    def evaluate(
+        self,
+        agent_did: str,
+        context: dict,
+    ) -> PolicyDecision:
+        """
+        Evaluate all applicable policies for an action.
+        
+        Args:
+            agent_did: The agent performing the action
+            context: Context for evaluation (action, data, etc.)
+            
+        Returns:
+            PolicyDecision with allow/deny and details
+        """
+        start = datetime.utcnow()
+        
+        # Get applicable policies
+        applicable = [p for p in self._policies.values() if p.applies_to(agent_did)]
+        
+        if not applicable:
+            # No policies = default allow
+            return PolicyDecision(
+                allowed=True,
+                action="allow",
+                reason="No applicable policies",
+                evaluated_at=start,
+            )
+        
+        # Evaluate rules in priority order
+        all_rules = []
+        for policy in applicable:
+            for rule in policy.rules:
+                all_rules.append((policy, rule))
+        
+        all_rules.sort(key=lambda x: x[1].priority, reverse=True)
+        
+        for policy, rule in all_rules:
+            if rule.evaluate(context):
+                # Rule matched
+                decision = self._apply_rule(rule, policy)
+                
+                # Calculate timing
+                elapsed = (datetime.utcnow() - start).total_seconds() * 1000
+                decision.evaluation_ms = elapsed
+                
+                return decision
+        
+        # No rules matched - use default action
+        default = applicable[0].default_action if applicable else "allow"
+        elapsed = (datetime.utcnow() - start).total_seconds() * 1000
+        
+        return PolicyDecision(
+            allowed=(default == "allow"),
+            action=default,
+            reason="No matching rules, using default",
+            evaluated_at=start,
+            evaluation_ms=elapsed,
+        )
+    
+    def _apply_rule(self, rule: PolicyRule, policy: Policy) -> PolicyDecision:
+        """Apply a matched rule."""
+        # Check rate limit if applicable
+        if rule.limit:
+            if self._is_rate_limited(rule):
+                return PolicyDecision(
+                    allowed=False,
+                    action="deny",
+                    matched_rule=rule.name,
+                    policy_name=policy.name,
+                    reason=f"Rate limit exceeded: {rule.limit}",
+                    rate_limited=True,
+                )
+            self._increment_rate_limit(rule)
+        
+        return PolicyDecision(
+            allowed=(rule.action == "allow"),
+            action=rule.action,
+            matched_rule=rule.name,
+            policy_name=policy.name,
+            reason=rule.description or f"Matched rule: {rule.name}",
+            approvers=rule.approvers if rule.action == "require_approval" else [],
+        )
+    
+    def _is_rate_limited(self, rule: PolicyRule) -> bool:
+        """Check if a rule is rate limited."""
+        if not rule.limit:
+            return False
+        
+        limit_key = rule.name
+        limit_data = self._rate_limits.get(limit_key)
+        
+        if not limit_data:
+            return False
+        
+        # Check if reset time passed
+        if datetime.utcnow() > limit_data["reset_at"]:
+            self._rate_limits[limit_key] = None
+            return False
+        
+        # Parse limit (e.g., "100/hour")
+        count, period = self._parse_limit(rule.limit)
+        
+        return limit_data["count"] >= count
+    
+    def _increment_rate_limit(self, rule: PolicyRule) -> None:
+        """Increment rate limit counter."""
+        if not rule.limit:
+            return
+        
+        limit_key = rule.name
+        count, period = self._parse_limit(rule.limit)
+        
+        if limit_key not in self._rate_limits or self._rate_limits[limit_key] is None:
+            from datetime import timedelta
+            self._rate_limits[limit_key] = {
+                "count": 0,
+                "reset_at": datetime.utcnow() + timedelta(seconds=period),
+            }
+        
+        self._rate_limits[limit_key]["count"] += 1
+    
+    def _parse_limit(self, limit: str) -> tuple[int, int]:
+        """Parse a limit string like '100/hour'."""
+        parts = limit.split("/")
+        count = int(parts[0])
+        
+        period_map = {
+            "second": 1,
+            "minute": 60,
+            "hour": 3600,
+            "day": 86400,
+        }
+        
+        period = period_map.get(parts[1], 3600)
+        return count, period
+    
+    def get_policy(self, name: str) -> Optional[Policy]:
+        """Get a policy by name."""
+        return self._policies.get(name)
+    
+    def list_policies(self) -> list[str]:
+        """List all loaded policy names."""
+        return list(self._policies.keys())
+    
+    def remove_policy(self, name: str) -> bool:
+        """Remove a policy."""
+        if name in self._policies:
+            del self._policies[name]
+            return True
+        return False

agentmesh/governance/shadow.py

@@ -0,0 +1,266 @@
+"""
+Shadow Mode
+
+Simulate agent behavior against real policies without execution.
+Shadow vs. production divergence target: <2% on replay dataset.
+"""
+
+from datetime import datetime
+from typing import Optional, Any
+from pydantic import BaseModel, Field
+from dataclasses import dataclass
+import uuid
+
+
+@dataclass
+class SimulatedAction:
+    """An action to simulate in shadow mode."""
+    
+    action_id: str
+    agent_did: str
+    action_type: str
+    context: dict
+    timestamp: datetime = None
+    
+    def __post_init__(self):
+        if self.timestamp is None:
+            self.timestamp = datetime.utcnow()
+
+
+class ShadowResult(BaseModel):
+    """Result of shadow mode evaluation."""
+    
+    action_id: str
+    
+    # Shadow evaluation
+    shadow_allowed: bool
+    shadow_action: str  # allow, deny, warn, etc.
+    shadow_rule: Optional[str] = None
+    
+    # Production evaluation (if available)
+    production_allowed: Optional[bool] = None
+    production_action: Optional[str] = None
+    production_rule: Optional[str] = None
+    
+    # Divergence
+    diverged: bool = False
+    divergence_reason: Optional[str] = None
+    
+    # Timing
+    evaluated_at: datetime = Field(default_factory=datetime.utcnow)
+    shadow_latency_ms: Optional[float] = None
+    production_latency_ms: Optional[float] = None
+
+
+class ShadowSession(BaseModel):
+    """A shadow mode evaluation session."""
+    
+    session_id: str = Field(default_factory=lambda: f"shadow_{uuid.uuid4().hex[:12]}")
+    started_at: datetime = Field(default_factory=datetime.utcnow)
+    
+    # Scope
+    agent_dids: list[str] = Field(default_factory=list)
+    policy_names: list[str] = Field(default_factory=list)
+    
+    # Results
+    total_evaluated: int = 0
+    total_diverged: int = 0
+    divergence_rate: float = 0.0
+    
+    # Detailed results
+    results: list[ShadowResult] = Field(default_factory=list)
+    
+    # Status
+    active: bool = True
+    ended_at: Optional[datetime] = None
+
+
+class ShadowMode:
+    """
+    Shadow mode for policy testing.
+    
+    Run new policies in shadow mode before production:
+    1. Load candidate policies
+    2. Replay production traffic or simulate actions
+    3. Compare shadow vs production decisions
+    4. Report divergence
+    
+    Target: <2% divergence on replay dataset.
+    """
+    
+    DIVERGENCE_TARGET = 0.02  # 2%
+    
+    def __init__(self, policy_engine):
+        """
+        Initialize shadow mode.
+        
+        Args:
+            policy_engine: PolicyEngine to test in shadow mode
+        """
+        self.policy_engine = policy_engine
+        self._sessions: dict[str, ShadowSession] = {}
+        self._active_session: Optional[str] = None
+    
+    def start_session(
+        self,
+        agent_dids: Optional[list[str]] = None,
+        policy_names: Optional[list[str]] = None,
+    ) -> ShadowSession:
+        """Start a new shadow evaluation session."""
+        session = ShadowSession(
+            agent_dids=agent_dids or [],
+            policy_names=policy_names or [],
+        )
+        
+        self._sessions[session.session_id] = session
+        self._active_session = session.session_id
+        
+        return session
+    
+    def evaluate(
+        self,
+        action: SimulatedAction,
+        production_decision: Optional[dict] = None,
+    ) -> ShadowResult:
+        """
+        Evaluate an action in shadow mode.
+        
+        Args:
+            action: The action to evaluate
+            production_decision: Optional actual production decision to compare
+            
+        Returns:
+            ShadowResult with comparison
+        """
+        start = datetime.utcnow()
+        
+        # Shadow evaluation
+        shadow_decision = self.policy_engine.evaluate(
+            agent_did=action.agent_did,
+            context=action.context,
+        )
+        
+        shadow_latency = (datetime.utcnow() - start).total_seconds() * 1000
+        
+        # Build result
+        result = ShadowResult(
+            action_id=action.action_id,
+            shadow_allowed=shadow_decision.allowed,
+            shadow_action=shadow_decision.action,
+            shadow_rule=shadow_decision.matched_rule,
+            shadow_latency_ms=shadow_latency,
+        )
+        
+        # Compare with production if available
+        if production_decision:
+            result.production_allowed = production_decision.get("allowed")
+            result.production_action = production_decision.get("action")
+            result.production_rule = production_decision.get("matched_rule")
+            result.production_latency_ms = production_decision.get("latency_ms")
+            
+            # Check for divergence
+            if result.shadow_allowed != result.production_allowed:
+                result.diverged = True
+                result.divergence_reason = (
+                    f"Shadow={result.shadow_action}, Production={result.production_action}"
+                )
+            elif result.shadow_action != result.production_action:
+                result.diverged = True
+                result.divergence_reason = f"Action mismatch: {result.shadow_action} vs {result.production_action}"
+        
+        # Record in session
+        if self._active_session:
+            session = self._sessions[self._active_session]
+            session.results.append(result)
+            session.total_evaluated += 1
+            if result.diverged:
+                session.total_diverged += 1
+            session.divergence_rate = (
+                session.total_diverged / session.total_evaluated
+                if session.total_evaluated > 0 else 0.0
+            )
+        
+        return result
+    
+    def replay_batch(
+        self,
+        actions: list[SimulatedAction],
+        production_decisions: Optional[list[dict]] = None,
+    ) -> list[ShadowResult]:
+        """
+        Replay a batch of actions in shadow mode.
+        
+        Args:
+            actions: List of actions to replay
+            production_decisions: Optional list of production decisions to compare
+        """
+        results = []
+        
+        for i, action in enumerate(actions):
+            prod_decision = None
+            if production_decisions and i < len(production_decisions):
+                prod_decision = production_decisions[i]
+            
+            result = self.evaluate(action, prod_decision)
+            results.append(result)
+        
+        return results
+    
+    def end_session(self, session_id: Optional[str] = None) -> ShadowSession:
+        """End a shadow session and return summary."""
+        sid = session_id or self._active_session
+        if not sid or sid not in self._sessions:
+            raise ValueError("No active session")
+        
+        session = self._sessions[sid]
+        session.active = False
+        session.ended_at = datetime.utcnow()
+        
+        if sid == self._active_session:
+            self._active_session = None
+        
+        return session
+    
+    def get_session(self, session_id: str) -> Optional[ShadowSession]:
+        """Get session by ID."""
+        return self._sessions.get(session_id)
+    
+    def get_divergence_report(self, session_id: Optional[str] = None) -> dict:
+        """Generate divergence report for a session."""
+        sid = session_id or self._active_session
+        if not sid or sid not in self._sessions:
+            return {"error": "No session found"}
+        
+        session = self._sessions[sid]
+        
+        # Group divergences by reason
+        divergence_reasons = {}
+        for result in session.results:
+            if result.diverged:
+                reason = result.divergence_reason or "unknown"
+                if reason not in divergence_reasons:
+                    divergence_reasons[reason] = 0
+                divergence_reasons[reason] += 1
+        
+        # Check if within target
+        within_target = session.divergence_rate <= self.DIVERGENCE_TARGET
+        
+        return {
+            "session_id": session.session_id,
+            "total_evaluated": session.total_evaluated,
+            "total_diverged": session.total_diverged,
+            "divergence_rate": session.divergence_rate,
+            "divergence_rate_pct": f"{session.divergence_rate * 100:.2f}%",
+            "target_rate_pct": f"{self.DIVERGENCE_TARGET * 100:.2f}%",
+            "within_target": within_target,
+            "divergence_breakdown": divergence_reasons,
+            "recommendation": (
+                "Ready for production" if within_target
+                else "Review divergent cases before production"
+            ),
+        }
+    
+    def is_ready_for_production(self, session_id: Optional[str] = None) -> bool:
+        """Check if shadow session shows policy is ready for production."""
+        report = self.get_divergence_report(session_id)
+        return report.get("within_target", False)

agentmesh/identity/__init__.py

@@ -0,0 +1,30 @@
+"""
+Identity & Zero-Trust Core (Layer 1)
+
+First-class agent identity with:
+- Cryptographically bound identities
+- Human sponsor accountability
+- Ephemeral credentials (15-min TTL)
+- SPIFFE/SVID workload identity
+"""
+
+from .agent_id import AgentIdentity, AgentDID
+from .credentials import Credential, CredentialManager
+from .delegation import DelegationChain, DelegationLink
+from .sponsor import HumanSponsor
+from .risk import RiskScorer, RiskScore
+from .spiffe import SPIFFEIdentity, SVID
+
+__all__ = [
+    "AgentIdentity",
+    "AgentDID",
+    "Credential",
+    "CredentialManager",
+    "DelegationChain",
+    "DelegationLink",
+    "HumanSponsor",
+    "RiskScorer",
+    "RiskScore",
+    "SPIFFEIdentity",
+    "SVID",
+]