agent_os_kernel 3.1.0__py3-none-any.whl

agent_os/policies/conflict_resolution.py

@@ -0,0 +1,270 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Policy Conflict Resolution.
+
+When multiple policies apply to the same agent action, the conflict
+resolution strategy determines which decision wins.
+
+Strategies
+----------
+- **DENY_OVERRIDES** (safest): If ANY matching rule denies, the action
+  is denied regardless of what other rules say. Standard in XACML and
+  most enterprise policy systems.
+- **ALLOW_OVERRIDES**: If ANY matching rule allows, the action is
+  allowed. Useful for exception-based governance where you want
+  explicit allow-rules to punch through default-deny policies.
+- **PRIORITY_FIRST_MATCH** (current default): Rules are sorted by
+  priority (highest first), and the first matching rule wins. This
+  preserves backward compatibility with the existing PolicyEngine.
+- **MOST_SPECIFIC_WINS**: Agent-scoped rules override tenant-scoped,
+  which override global-scoped. Within the same scope, priority breaks
+  ties. Models the intuition that "closer policies override distant ones."
+
+Scopes
+------
+Each ``Policy`` can declare a ``scope`` that indicates its breadth:
+
+- ``global``: Organization-wide default policies
+- ``tenant``: Applied to a specific tenant or team
+- ``agent``: Applied to a specific agent instance
+
+When ``MOST_SPECIFIC_WINS`` is active, scope determines precedence.
+When other strategies are active, scope is informational metadata.
+
+Usage::
+
+    from agentmesh.governance.conflict_resolution import (
+        ConflictResolutionStrategy,
+        PolicyScope,
+        PolicyConflictResolver,
+    )
+
+    resolver = PolicyConflictResolver(ConflictResolutionStrategy.DENY_OVERRIDES)
+    final = resolver.resolve(candidate_decisions)
+"""
+
+from __future__ import annotations
+
+import logging
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+logger = logging.getLogger(__name__)
+
+
+class ConflictResolutionStrategy(str, Enum):
+    """Strategy for resolving conflicts between competing policy decisions."""
+
+    DENY_OVERRIDES = "deny_overrides"
+    ALLOW_OVERRIDES = "allow_overrides"
+    PRIORITY_FIRST_MATCH = "priority_first_match"
+    MOST_SPECIFIC_WINS = "most_specific_wins"
+
+
+class PolicyScope(str, Enum):
+    """Breadth of a policy's applicability.
+
+    Specificity order (most → least): AGENT > ORGANIZATION > TENANT > GLOBAL.
+    """
+
+    GLOBAL = "global"
+    TENANT = "tenant"
+    ORGANIZATION = "organization"
+    AGENT = "agent"
+
+
+# Specificity rank: higher = more specific
+_SCOPE_SPECIFICITY: dict[PolicyScope, int] = {
+    PolicyScope.GLOBAL: 0,
+    PolicyScope.TENANT: 1,
+    PolicyScope.ORGANIZATION: 2,
+    PolicyScope.AGENT: 3,
+}
+
+
+class CandidateDecision(BaseModel):
+    """A single policy decision candidate awaiting conflict resolution.
+
+    Groups a decision with its originating policy metadata so the
+    resolver can apply scope- and priority-aware strategies.
+
+    Attributes:
+        action: The action the rule dictates (allow, deny, warn, etc.).
+        priority: Numeric priority from the matched rule.
+        scope: Scope of the policy that produced this decision.
+        policy_name: Name of the originating policy.
+        rule_name: Name of the matched rule.
+        reason: Human-readable explanation.
+        approvers: Required approvers for ``require_approval`` actions.
+    """
+
+    action: str
+    priority: int = 0
+    scope: PolicyScope = PolicyScope.GLOBAL
+    policy_name: str = ""
+    rule_name: str = ""
+    reason: str = ""
+    approvers: list[str] = Field(default_factory=list)
+
+    @property
+    def is_deny(self) -> bool:
+        return self.action == "deny"
+
+    @property
+    def is_allow(self) -> bool:
+        return self.action == "allow"
+
+    @property
+    def specificity(self) -> int:
+        return _SCOPE_SPECIFICITY.get(self.scope, 0)
+
+
+class ResolutionResult(BaseModel):
+    """Outcome of conflict resolution.
+
+    Attributes:
+        winning_decision: The decision that prevailed.
+        strategy_used: Which strategy resolved the conflict.
+        candidates_evaluated: How many candidates were considered.
+        conflict_detected: Whether genuinely conflicting decisions existed.
+        resolution_trace: Human-readable trace of the resolution logic.
+    """
+
+    winning_decision: CandidateDecision
+    strategy_used: ConflictResolutionStrategy
+    candidates_evaluated: int = 0
+    conflict_detected: bool = False
+    resolution_trace: list[str] = Field(default_factory=list)
+
+
+class PolicyConflictResolver:
+    """Resolves conflicts between competing policy decisions.
+
+    Args:
+        strategy: The conflict resolution strategy to apply.
+    """
+
+    def __init__(
+        self,
+        strategy: ConflictResolutionStrategy = ConflictResolutionStrategy.PRIORITY_FIRST_MATCH,
+    ) -> None:
+        self.strategy = strategy
+
+    def resolve(self, candidates: list[CandidateDecision]) -> ResolutionResult:
+        """Resolve a list of candidate decisions into a single winner.
+
+        Args:
+            candidates: One or more candidate decisions from matching rules.
+
+        Returns:
+            A ``ResolutionResult`` containing the winning decision and
+            a trace of the resolution logic.
+
+        Raises:
+            ValueError: If ``candidates`` is empty.
+        """
+        if not candidates:
+            raise ValueError("Cannot resolve conflict with zero candidates")
+
+        if len(candidates) == 1:
+            return ResolutionResult(
+                winning_decision=candidates[0],
+                strategy_used=self.strategy,
+                candidates_evaluated=1,
+                conflict_detected=False,
+                resolution_trace=[f"Single candidate: {candidates[0].rule_name} → {candidates[0].action}"],
+            )
+
+        # Detect genuine conflict (mix of allow and deny)
+        actions = {c.action for c in candidates}
+        conflict_detected = "allow" in actions and "deny" in actions
+
+        dispatch = {
+            ConflictResolutionStrategy.DENY_OVERRIDES: self._deny_overrides,
+            ConflictResolutionStrategy.ALLOW_OVERRIDES: self._allow_overrides,
+            ConflictResolutionStrategy.PRIORITY_FIRST_MATCH: self._priority_first_match,
+            ConflictResolutionStrategy.MOST_SPECIFIC_WINS: self._most_specific_wins,
+        }
+
+        winner, trace = dispatch[self.strategy](candidates)
+
+        return ResolutionResult(
+            winning_decision=winner,
+            strategy_used=self.strategy,
+            candidates_evaluated=len(candidates),
+            conflict_detected=conflict_detected,
+            resolution_trace=trace,
+        )
+
+    # ── Strategy implementations ────────────────────────────
+
+    def _deny_overrides(
+        self, candidates: list[CandidateDecision]
+    ) -> tuple[CandidateDecision, list[str]]:
+        """DENY_OVERRIDES: any deny wins. Among denies, highest priority wins."""
+        trace = []
+        denies = [c for c in candidates if c.is_deny]
+        if denies:
+            denies.sort(key=lambda c: c.priority, reverse=True)
+            winner = denies[0]
+            trace.append(f"DENY_OVERRIDES: {len(denies)} deny rule(s) found")
+            trace.append(f"Winner: {winner.rule_name} (priority={winner.priority}, scope={winner.scope.value})")
+            return winner, trace
+
+        # No denies — pick highest-priority allow
+        candidates_sorted = sorted(candidates, key=lambda c: c.priority, reverse=True)
+        winner = candidates_sorted[0]
+        trace.append("DENY_OVERRIDES: no deny rules, selecting highest-priority allow")
+        trace.append(f"Winner: {winner.rule_name} (priority={winner.priority})")
+        return winner, trace
+
+    def _allow_overrides(
+        self, candidates: list[CandidateDecision]
+    ) -> tuple[CandidateDecision, list[str]]:
+        """ALLOW_OVERRIDES: any allow wins. Among allows, highest priority wins."""
+        trace = []
+        allows = [c for c in candidates if c.is_allow]
+        if allows:
+            allows.sort(key=lambda c: c.priority, reverse=True)
+            winner = allows[0]
+            trace.append(f"ALLOW_OVERRIDES: {len(allows)} allow rule(s) found")
+            trace.append(f"Winner: {winner.rule_name} (priority={winner.priority}, scope={winner.scope.value})")
+            return winner, trace
+
+        # No allows — pick highest-priority deny
+        candidates_sorted = sorted(candidates, key=lambda c: c.priority, reverse=True)
+        winner = candidates_sorted[0]
+        trace.append("ALLOW_OVERRIDES: no allow rules, selecting highest-priority deny")
+        trace.append(f"Winner: {winner.rule_name} (priority={winner.priority})")
+        return winner, trace
+
+    def _priority_first_match(
+        self, candidates: list[CandidateDecision]
+    ) -> tuple[CandidateDecision, list[str]]:
+        """PRIORITY_FIRST_MATCH: highest priority wins regardless of action."""
+        sorted_candidates = sorted(candidates, key=lambda c: c.priority, reverse=True)
+        winner = sorted_candidates[0]
+        trace = [
+            f"PRIORITY_FIRST_MATCH: {len(candidates)} candidates",
+            f"Winner: {winner.rule_name} (priority={winner.priority}, action={winner.action})",
+        ]
+        return winner, trace
+
+    def _most_specific_wins(
+        self, candidates: list[CandidateDecision]
+    ) -> tuple[CandidateDecision, list[str]]:
+        """MOST_SPECIFIC_WINS: agent > tenant > global. Priority breaks ties."""
+        sorted_candidates = sorted(
+            candidates,
+            key=lambda c: (c.specificity, c.priority),
+            reverse=True,
+        )
+        winner = sorted_candidates[0]
+        trace = [
+            f"MOST_SPECIFIC_WINS: {len(candidates)} candidates",
+            f"Specificity ranking: {[(c.rule_name, c.scope.value, c.specificity) for c in sorted_candidates]}",
+            f"Winner: {winner.rule_name} (scope={winner.scope.value}, priority={winner.priority}, action={winner.action})",
+        ]
+        return winner, trace

agent_os/policies/data_classification.py

@@ -0,0 +1,252 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""Data-layer ABAC policies for AI agent governance.
+
+Extends the policy engine beyond tool-level to data-level enforcement.
+Agents are checked not just for which tools they can use, but which
+data classifications they can access.
+
+Addresses the market gap where 63% of organizations cannot stop
+their AI from accessing unauthorized data (Kiteworks 2026 research).
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timezone
+from enum import IntEnum
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class DataClassification(IntEnum):
+    """Sensitivity levels for data classification, ordered by sensitivity."""
+
+    PUBLIC = 0
+    INTERNAL = 1
+    CONFIDENTIAL = 2
+    RESTRICTED = 3
+    TOP_SECRET = 4
+
+
+class DataLabel(BaseModel):
+    """Label describing data sensitivity and handling requirements."""
+
+    classification: DataClassification
+    categories: list[str] = Field(
+        default_factory=list,
+        description="Data categories such as PII, PHI, PCI, GDPR, ITAR",
+    )
+    owner: str = ""
+    retention_days: int = 90
+    geography: str = ""
+
+
+class ABACPolicy(BaseModel):
+    """Attribute-Based Access Control policy for an agent."""
+
+    agent_id: str
+    allowed_classifications: list[DataClassification] = Field(default_factory=list)
+    allowed_categories: list[str] = Field(default_factory=list)
+    denied_categories: list[str] = Field(default_factory=list)
+    required_geography: Optional[str] = None
+    max_classification: DataClassification = DataClassification.PUBLIC
+
+
+class DataAccessDecision(BaseModel):
+    """Result of evaluating an agent's data access request."""
+
+    allowed: bool
+    reason: str
+    agent_id: str
+    data_label: DataLabel
+    matched_policy: Optional[str] = None
+    evaluated_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+
+class DataAccessEvaluator:
+    """Evaluates agent data-access requests against ABAC policies.
+
+    When multiple policies exist for the same agent, the most restrictive
+    result wins (deny takes precedence over allow).
+    """
+
+    def __init__(self, policies: list[ABACPolicy]) -> None:
+        self._policies = policies
+
+    def evaluate(self, agent_id: str, data_label: DataLabel) -> DataAccessDecision:
+        """Check whether *agent_id* may access data described by *data_label*."""
+        agent_policies = [p for p in self._policies if p.agent_id == agent_id]
+        if not agent_policies:
+            return DataAccessDecision(
+                allowed=False,
+                reason="No ABAC policy registered for agent",
+                agent_id=agent_id,
+                data_label=data_label,
+            )
+
+        # Evaluate each policy; any denial means overall denial (most restrictive wins)
+        for policy in agent_policies:
+            decision = self._evaluate_single(agent_id, data_label, policy)
+            if not decision.allowed:
+                return decision
+
+        # All policies passed
+        return DataAccessDecision(
+            allowed=True,
+            reason="Access permitted by all applicable policies",
+            agent_id=agent_id,
+            data_label=data_label,
+            matched_policy=agent_policies[0].agent_id,
+        )
+
+    @staticmethod
+    def _evaluate_single(
+        agent_id: str, data_label: DataLabel, policy: ABACPolicy
+    ) -> DataAccessDecision:
+        policy_ref = policy.agent_id
+
+        if data_label.classification > policy.max_classification:
+            return DataAccessDecision(
+                allowed=False,
+                reason=(
+                    f"Classification {data_label.classification.name} exceeds "
+                    f"max {policy.max_classification.name}"
+                ),
+                agent_id=agent_id,
+                data_label=data_label,
+                matched_policy=policy_ref,
+            )
+
+        if (
+            policy.allowed_classifications
+            and data_label.classification not in policy.allowed_classifications
+        ):
+            return DataAccessDecision(
+                allowed=False,
+                reason=(
+                    f"Classification {data_label.classification.name} not in "
+                    f"allowed list"
+                ),
+                agent_id=agent_id,
+                data_label=data_label,
+                matched_policy=policy_ref,
+            )
+
+        for cat in data_label.categories:
+            if cat in policy.denied_categories:
+                return DataAccessDecision(
+                    allowed=False,
+                    reason=f"Category '{cat}' is explicitly denied",
+                    agent_id=agent_id,
+                    data_label=data_label,
+                    matched_policy=policy_ref,
+                )
+
+        if policy.allowed_categories:
+            for cat in data_label.categories:
+                if cat not in policy.allowed_categories:
+                    return DataAccessDecision(
+                        allowed=False,
+                        reason=f"Category '{cat}' not in allowed categories",
+                        agent_id=agent_id,
+                        data_label=data_label,
+                        matched_policy=policy_ref,
+                    )
+
+        if (
+            policy.required_geography
+            and data_label.geography
+            and data_label.geography != policy.required_geography
+        ):
+            return DataAccessDecision(
+                allowed=False,
+                reason=(
+                    f"Geography '{data_label.geography}' does not match "
+                    f"required '{policy.required_geography}'"
+                ),
+                agent_id=agent_id,
+                data_label=data_label,
+                matched_policy=policy_ref,
+            )
+
+        return DataAccessDecision(
+            allowed=True,
+            reason="Policy passed",
+            agent_id=agent_id,
+            data_label=data_label,
+            matched_policy=policy_ref,
+        )
+
+
+# ---------------------------------------------------------------------------
+# PII / PHI / PCI detection helpers
+# ---------------------------------------------------------------------------
+
+_SSN_RE = re.compile(r"\b\d{3}-\d{2}-\d{4}\b")
+_EMAIL_RE = re.compile(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b")
+_PHONE_RE = re.compile(
+    r"\b(?:\+1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b"
+)
+
+_MRN_RE = re.compile(r"\bMRN[-:\s]*\d{6,10}\b", re.IGNORECASE)
+_ICD_RE = re.compile(r"\b[A-Z]\d{2}(?:\.\d{1,4})?\b")
+
+_CC_RE = re.compile(r"\b(?:\d[ -]*?){13,19}\b")
+
+
+def detect_pii(text: str) -> list[str]:
+    """Detect PII patterns (SSN, email, phone) in *text*."""
+    findings: list[str] = []
+    if _SSN_RE.search(text):
+        findings.append("SSN")
+    if _EMAIL_RE.search(text):
+        findings.append("email")
+    if _PHONE_RE.search(text):
+        findings.append("phone")
+    return findings
+
+
+def detect_phi(text: str) -> list[str]:
+    """Detect PHI patterns (medical record numbers, diagnosis codes)."""
+    findings: list[str] = []
+    if _MRN_RE.search(text):
+        findings.append("MRN")
+    if _ICD_RE.search(text):
+        findings.append("ICD-code")
+    return findings
+
+
+def detect_pci(text: str) -> list[str]:
+    """Detect PCI patterns (credit card numbers)."""
+    findings: list[str] = []
+    if _CC_RE.search(text):
+        findings.append("credit-card")
+    return findings
+
+
+def classify_text(text: str) -> DataLabel:
+    """Auto-classify *text* based on detected sensitive-data patterns."""
+    categories: list[str] = []
+    classification = DataClassification.PUBLIC
+
+    pii = detect_pii(text)
+    if pii:
+        categories.append("PII")
+        classification = max(classification, DataClassification.CONFIDENTIAL)
+
+    phi = detect_phi(text)
+    if phi:
+        categories.append("PHI")
+        classification = max(classification, DataClassification.RESTRICTED)
+
+    pci = detect_pci(text)
+    if pci:
+        categories.append("PCI")
+        classification = max(classification, DataClassification.CONFIDENTIAL)
+
+    if not categories:
+        classification = DataClassification.PUBLIC
+
+    return DataLabel(classification=classification, categories=categories)