actshield 0.9.0__py3-none-any.whl

actshield/policy/evaluator.py

@@ -0,0 +1,294 @@
+"""Deterministic policy evaluator enforcing security boundaries."""
+
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+from actshield.agents.identity import AgentTrustLevel
+from actshield.context.context import Context
+from actshield.context.taint import TaintState
+from actshield.decisions.decision import DecisionAction, SecurityDecision
+from actshield.integrations.ai_secura import SecurityAnalysis, SecurityContext
+from actshield.integrations.apiris import APIAnalysis
+from actshield.policy.intent import DeterministicIntentAnalyzer, IntentAlignmentResult, IntentAnalyzer
+from actshield.policy.policy import Policy
+from actshield.risk.models import RiskFactorBreakdown, RiskLevel, RiskSignal
+from actshield.tools.tool import SensitivityLevel, ToolDefinition, ToolRequest
+from actshield.tracing.correlation import CorrelationContext, generate_id
+from actshield.tracing.events import EventType
+
+if TYPE_CHECKING:
+    from actshield.client import ActShield
+
+
+class PolicyEvaluator:
+    """Deterministic security policy engine for actshield.
+    
+    Adheres strictly to the architectural principles:
+    - AI reasons (AI Secura / Intent Analysis).
+    - Deterministic policy evaluates signals, state, authority containment, intent alignment,
+      and data taint to render decisions:
+      ALLOW / MONITOR / HUMAN_APPROVAL / QUARANTINE / BLOCK / REVOKE.
+    """
+
+    def __init__(self, guard: "ActShield") -> None:
+        self.guard = guard
+        self.intent_analyzer: IntentAnalyzer = DeterministicIntentAnalyzer()
+        self.default_policies: List[Policy] = []
+
+    def evaluate(
+        self,
+        tool_def: ToolDefinition,
+        request: ToolRequest,
+        ctx: Optional[CorrelationContext],
+        active_contexts: List[Context],
+    ) -> SecurityDecision:
+        trace_id = ctx.trace_id if ctx else generate_id("trc")
+        evidence_refs: List[str] = []
+        signals: List[RiskSignal] = []
+
+        # 1. Resolve Acting Agent
+        agent_id = request.agent_id or (ctx.agent_id if ctx else None)
+        acting_agent = self.guard.agent_registry.get(agent_id) if agent_id else None
+
+        # 2. Resolve Active Delegation Chain
+        delegation_id = ctx.delegation_id if ctx else None
+        active_delegation = self.guard.delegation_registry.get(delegation_id) if delegation_id else None
+
+        if active_delegation:
+            evidence_refs.append(active_delegation.delegation_id)
+
+        # 3. Influencing Contexts & Taint Assessment
+        influencing_ctx_ids = [c.context_id for c in active_contexts if c is not None]
+        for c in active_contexts:
+            if c.context_id and c.context_id not in evidence_refs:
+                evidence_refs.append(c.context_id)
+
+        has_tainted_context = any(c.taint_state in (TaintState.TAINTED, TaintState.UNTRUSTED) for c in active_contexts)
+        has_untrusted_origin = any(c.source.value in ("external_mcp", "external_api") or c.trust_level == "untrusted" or c.taint_state == TaintState.UNTRUSTED for c in active_contexts)
+        is_critical_sink = tool_def.sensitivity in (SensitivityLevel.HIGH, SensitivityLevel.CRITICAL)
+
+
+        # 4. Authority Containment Evaluation
+        authority_violation = False
+        authority_reason = ""
+        delegated_caps: List[str] = []
+
+        if active_delegation is not None:
+            delegated_caps = list(active_delegation.authority_grant.granted_capabilities)
+            for req_cap in tool_def.required_capabilities:
+                if not active_delegation.authority_grant.contains_capability(req_cap):
+                    authority_violation = True
+                    authority_reason = f"Delegated authority {delegated_caps} lacks required capability '{req_cap}'"
+                    break
+        elif acting_agent is not None:
+            delegated_caps = acting_agent.capability_names()
+            for req_cap in tool_def.required_capabilities:
+                if not acting_agent.has_capability(req_cap):
+                    authority_violation = True
+                    authority_reason = f"Agent '{acting_agent.name}' does not possess declared capability '{req_cap}'"
+                    break
+
+        authority_containment_report = {
+            "requesting_agent": acting_agent.name if acting_agent else agent_id,
+            "required_capabilities": tool_def.required_capabilities,
+            "delegated_capabilities": delegated_caps,
+            "delegation_id": delegation_id,
+            "contained": not authority_violation,
+            "reason": authority_reason if authority_violation else "Authority containment verified.",
+        }
+
+        # 5. Intent Alignment Evaluation
+        original_intent = ctx.metadata.get("intent", "Unspecified task intent") if ctx else "Unspecified task intent"
+        target_res_name = tool_def.target_resources[0].name if tool_def.target_resources else None
+        
+        intent_res: IntentAlignmentResult = self.intent_analyzer.analyze(
+            original_intent=original_intent,
+            tool_name=tool_def.name,
+            required_capabilities=tool_def.required_capabilities,
+            target_resource_sensitivity=tool_def.sensitivity.value,
+            target_resource_name=target_res_name,
+            arguments=request.arguments,
+        )
+        intent_violation = intent_res.is_violation
+
+        intent_alignment_report = {
+            "original_intent": original_intent,
+            "action_name": tool_def.name,
+            "status": intent_res.status.value,
+            "aligned": not intent_violation,
+            "explanation": intent_res.explanation,
+            "indicators": intent_res.matched_indicators,
+        }
+
+        # 6. Compute Deterministic Risk Breakdown
+        risk_breakdown = RiskFactorBreakdown.compute(
+            has_tainted_context=has_tainted_context,
+            is_critical_sink=is_critical_sink,
+            has_authority_violation=authority_violation,
+            has_intent_violation=intent_violation,
+            is_untrusted_origin=has_untrusted_origin,
+        )
+
+        # 7. Build Structured Explanation
+        structured_explanation = {
+            "agent": acting_agent.name if acting_agent else agent_id,
+            "requested_tool": tool_def.name,
+            "required_capabilities": tool_def.required_capabilities,
+            "delegated_capabilities": delegated_caps,
+            "authority_containment": "PASSED" if not authority_violation else "FAILED",
+            "original_intent": original_intent,
+            "intent_alignment": "PASSED" if not intent_violation else "FAILED",
+            "context_sources": [c.source.value for c in active_contexts],
+            "context_taint_states": [c.taint_state.value for c in active_contexts],
+            "sensitive_sink": target_res_name or tool_def.name,
+            "sink_sensitivity": tool_def.sensitivity.value,
+            "risk_factors": risk_breakdown.risk_factors,
+            "total_risk_score": risk_breakdown.total_score,
+        }
+
+        # 8. Deterministic Decision Rule Evaluations
+        # Rule 8a: Authority Escalation Violation -> BLOCK
+        if authority_violation:
+            reason_code = "DELEGATION_AUTHORITY_EXCEEDED" if active_delegation else "MISSING_AGENT_CAPABILITY"
+            explanation = (
+                f"Agent '{acting_agent.name if acting_agent else agent_id}' was delegated authority "
+                f"lacking required capability '{tool_def.required_capabilities}' for tool '{tool_def.name}'."
+                if active_delegation else
+                f"Agent '{acting_agent.name if acting_agent else agent_id}' does not possess declared capability "
+                f"required to invoke tool '{tool_def.name}'."
+            )
+            decision = SecurityDecision(
+                action=DecisionAction.BLOCK,
+                risk_level=RiskLevel.HIGH if risk_breakdown.total_score < 0.7 else RiskLevel.CRITICAL,
+                risk_score=risk_breakdown.total_score,
+                reason_code=reason_code,
+                explanation=explanation,
+                trace_id=trace_id,
+                evidence_references=evidence_refs,
+                influencing_context_ids=influencing_ctx_ids,
+                authority_containment=authority_containment_report,
+                intent_alignment=intent_alignment_report,
+                risk_breakdown=risk_breakdown,
+                structured_explanation=structured_explanation,
+            )
+            self._emit_decision_events(tool_def, request, decision)
+            return decision
+
+        # Rule 8b: Tainted Context flowing into Sensitive Sink -> BLOCK
+        if has_tainted_context and is_critical_sink:
+            if self.guard.config.block_tainted_sink_access:
+                decision = SecurityDecision(
+                    action=DecisionAction.BLOCK,
+                    risk_level=RiskLevel.CRITICAL,
+                    risk_score=risk_breakdown.total_score,
+                    reason_code="TAINTED_CONTEXT_INTO_SENSITIVE_SINK",
+                    explanation=(
+                        f"Tainted or injected context attempted to flow into {tool_def.sensitivity.value} "
+                        f"sensitive tool/resource '{tool_def.name}' without explicit verification/sanitization."
+                    ),
+                    trace_id=trace_id,
+                    evidence_references=evidence_refs,
+                    influencing_context_ids=influencing_ctx_ids,
+                    authority_containment=authority_containment_report,
+                    intent_alignment=intent_alignment_report,
+                    risk_breakdown=risk_breakdown,
+                    structured_explanation=structured_explanation,
+                )
+                self._emit_decision_events(tool_def, request, decision)
+                return decision
+
+        # Rule 8c: Untrusted Agent Sensitive Access -> BLOCK
+        if acting_agent is not None and acting_agent.trust_level == AgentTrustLevel.UNTRUSTED and tool_def.sensitivity != SensitivityLevel.LOW:
+            decision = SecurityDecision(
+                action=DecisionAction.BLOCK,
+                risk_level=RiskLevel.HIGH,
+                risk_score=risk_breakdown.total_score,
+                reason_code="UNTRUSTED_AGENT_SENSITIVE_ACCESS",
+                explanation=f"Untrusted agent '{acting_agent.name}' is prohibited from invoking {tool_def.sensitivity.value} tool '{tool_def.name}'.",
+                trace_id=trace_id,
+                evidence_references=evidence_refs,
+                influencing_context_ids=influencing_ctx_ids,
+                authority_containment=authority_containment_report,
+                intent_alignment=intent_alignment_report,
+                risk_breakdown=risk_breakdown,
+                structured_explanation=structured_explanation,
+            )
+            self._emit_decision_events(tool_def, request, decision)
+            return decision
+
+        # Rule 8d: User Intent Alignment Violation -> BLOCK
+        if intent_violation and is_critical_sink:
+            decision = SecurityDecision(
+                action=DecisionAction.BLOCK,
+                risk_level=RiskLevel.HIGH,
+                risk_score=risk_breakdown.total_score,
+                reason_code="INTENT_ALIGNMENT_VIOLATION",
+                explanation=intent_res.explanation,
+                trace_id=trace_id,
+                evidence_references=evidence_refs,
+                influencing_context_ids=influencing_ctx_ids,
+                authority_containment=authority_containment_report,
+                intent_alignment=intent_alignment_report,
+                risk_breakdown=risk_breakdown,
+                structured_explanation=structured_explanation,
+            )
+            self._emit_decision_events(tool_def, request, decision)
+            return decision
+
+        # Rule 8e: Default Allowed / Monitored
+        action = DecisionAction.ALLOW if risk_breakdown.total_score < 0.4 else DecisionAction.MONITOR
+        decision = SecurityDecision(
+            action=action,
+            risk_level=RiskLevel.LOW if action == DecisionAction.ALLOW else RiskLevel.MEDIUM,
+            risk_score=risk_breakdown.total_score,
+            reason_code="POLICY_ALLOW_STANDARD" if action == DecisionAction.ALLOW else "RISK_MONITORED",
+            explanation="Action permitted under standard security policy." if action == DecisionAction.ALLOW else "Action permitted under continuous security monitoring.",
+            trace_id=trace_id,
+            evidence_references=evidence_refs,
+            influencing_context_ids=influencing_ctx_ids,
+            authority_containment=authority_containment_report,
+            intent_alignment=intent_alignment_report,
+            risk_breakdown=risk_breakdown,
+            structured_explanation=structured_explanation,
+        )
+
+        self._emit_decision_events(tool_def, request, decision)
+        return decision
+
+    def _emit_decision_events(
+        self,
+        tool_def: ToolDefinition,
+        request: ToolRequest,
+        decision: SecurityDecision,
+    ) -> None:
+        """Emit security.evaluated and security.decision events to the tracer."""
+        self.guard.emit_event(
+            event_type=EventType.SECURITY_EVALUATED,
+            trace_id=decision.trace_id,
+            agent_id=request.agent_id,
+            payload={
+                "tool_id": tool_def.tool_id,
+                "tool_name": tool_def.name,
+                "risk_score": decision.risk_score,
+                "risk_level": decision.risk_level.value,
+                "authority_contained": decision.authority_containment.get("contained", True),
+                "intent_aligned": decision.intent_alignment.get("aligned", True),
+            }
+        )
+
+        self.guard.emit_event(
+            event_type=EventType.SECURITY_DECISION,
+            trace_id=decision.trace_id,
+            agent_id=request.agent_id,
+            payload={
+                "decision_id": decision.decision_id,
+                "action": decision.action.value,
+                "reason_code": decision.reason_code,
+                "explanation": decision.explanation,
+                "risk_score": decision.risk_score,
+                "evidence_references": decision.evidence_references,
+                "influencing_context_ids": decision.influencing_context_ids,
+                "structured_explanation": decision.structured_explanation,
+            }
+        )
+
+

actshield/policy/intent.py

@@ -0,0 +1,113 @@
+"""Intent tracking and deterministic intent alignment analysis."""
+
+from enum import Enum
+from typing import Any, Dict, List, Optional, Protocol, runtime_checkable
+from pydantic import BaseModel, Field
+
+
+class IntentAlignmentStatus(str, Enum):
+    """Alignment status between original user intent and requested agent action."""
+    ALIGNED = "ALIGNED"
+    MISALIGNED = "MISALIGNED"
+    VIOLATION = "VIOLATION"
+    UNKNOWN = "UNKNOWN"
+
+
+class IntentAlignmentResult(BaseModel):
+    """Result of intent alignment verification."""
+    status: IntentAlignmentStatus = IntentAlignmentStatus.ALIGNED
+    score: float = Field(default=0.0, ge=0.0, le=1.0, description="Risk contribution (0.0 = aligned, 1.0 = direct violation)")
+    explanation: str = Field(default="Action aligns with original user intent.")
+    matched_indicators: List[str] = Field(default_factory=list)
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+    def __init__(self, **data: Any) -> None:
+        if "reason" in data and "explanation" not in data:
+            data["explanation"] = data["reason"]
+        super().__init__(**data)
+
+    @property
+    def is_violation(self) -> bool:
+        return self.status in (IntentAlignmentStatus.VIOLATION, IntentAlignmentStatus.MISALIGNED)
+
+    @property
+    def reason(self) -> str:
+        return self.explanation
+
+
+
+
+@runtime_checkable
+class IntentAnalyzer(Protocol):
+    """Protocol for intent alignment analysis (extensible for AI Secura in Phase 5)."""
+
+    def analyze(
+        self,
+        original_intent: str,
+        tool_name: str,
+        required_capabilities: List[str],
+        target_resource_sensitivity: str,
+        target_resource_name: Optional[str] = None,
+        arguments: Optional[Dict[str, Any]] = None,
+    ) -> IntentAlignmentResult:
+        """Evaluate if the requested action and required capability remain within the original user intent."""
+        ...
+
+
+class DeterministicIntentAnalyzer(IntentAnalyzer):
+    """Deterministic, explainable baseline intent analyzer for Phase 2."""
+
+    def analyze(
+        self,
+        original_intent: str,
+        tool_name: str,
+        required_capabilities: List[str],
+        target_resource_sensitivity: str,
+        target_resource_name: Optional[str] = None,
+        arguments: Optional[Dict[str, Any]] = None,
+    ) -> IntentAlignmentResult:
+        intent_lower = (original_intent or "").lower()
+        tool_lower = (tool_name or "").lower()
+        res_lower = (target_resource_name or "").lower()
+        caps = [c.lower() for c in required_capabilities]
+
+        indicators: List[str] = []
+
+        # Check for public/financial scope vs customer PII / sensitive data
+        is_public_financial_intent = any(k in intent_lower for k in ("public", "financial", "sec", "annual report", "10-k", "market"))
+        is_customer_pii_target = any("customer" in c for c in caps) or "customer" in tool_lower or "customer" in res_lower or "pii" in res_lower
+        
+        if is_public_financial_intent and is_customer_pii_target:
+            indicators.append("PUBLIC_INTENT_VS_CUSTOMER_PII_SINK")
+            return IntentAlignmentResult(
+                status=IntentAlignmentStatus.VIOLATION,
+                score=0.85,
+                explanation=(
+                    f"Intent Violation: Original user intent was scoped to public financial information ('{original_intent}'), "
+                    f"but requested tool '{tool_name}' targets sensitive customer records/PII."
+                ),
+                matched_indicators=indicators,
+            )
+
+        # Check for administrative / destructive actions in audit intents
+        is_read_intent = any(k in intent_lower for k in ("analyze", "audit", "find", "read", "extract", "search"))
+        is_destructive_action = any(k in tool_lower for k in ("delete", "drop", "write", "modify", "admin", "truncate"))
+
+        if is_read_intent and is_destructive_action:
+            indicators.append("READ_AUDIT_INTENT_VS_DESTRUCTIVE_ACTION")
+            return IntentAlignmentResult(
+                status=IntentAlignmentStatus.VIOLATION,
+                score=0.95,
+                explanation=(
+                    f"Intent Violation: Original intent is read/audit ('{original_intent}'), "
+                    f"but requested tool '{tool_name}' performs destructive modification."
+                ),
+                matched_indicators=indicators,
+            )
+
+        return IntentAlignmentResult(
+            status=IntentAlignmentStatus.ALIGNED,
+            score=0.0,
+            explanation=f"Action '{tool_name}' aligns with declared user intent.",
+            matched_indicators=[],
+        )

actshield/policy/policy.py

@@ -0,0 +1,48 @@
+"""Deterministic security policy definitions."""
+
+from enum import Enum
+from typing import Any, Callable, Dict, List, Optional
+from pydantic import BaseModel, Field
+
+from actshield.decisions.decision import DecisionAction
+from actshield.risk.models import RiskLevel
+from actshield.tracing.correlation import generate_id
+
+
+class RuleCondition(str, Enum):
+    """Common condition types evaluated by policy rules."""
+    CAPABILITY_REQUIRED = "CAPABILITY_REQUIRED"
+    TAINT_RESTRICTION = "TAINT_RESTRICTION"
+    TRUST_LEVEL_MINIMUM = "TRUST_LEVEL_MINIMUM"
+    SENSITIVITY_THRESHOLD = "SENSITIVITY_THRESHOLD"
+    APIRIS_RISK_THRESHOLD = "APIRIS_RISK_THRESHOLD"
+    AI_SECURA_INTENT_DRIFT = "AI_SECURA_INTENT_DRIFT"
+    CUSTOM = "CUSTOM"
+
+
+class PolicyRule(BaseModel):
+    """An individual deterministic rule within a Policy."""
+    
+    rule_id: str = Field(default_factory=lambda: generate_id("rule"))
+    name: str = Field(..., description="Human-readable rule name")
+    description: str = Field(default="")
+    condition_type: RuleCondition = Field(default=RuleCondition.CUSTOM)
+    target_action: DecisionAction = Field(default=DecisionAction.BLOCK, description="Enforcement action if rule matches")
+    risk_level: RiskLevel = Field(default=RiskLevel.HIGH)
+    reason_code: str = Field(default="POLICY_VIOLATION")
+    explanation_template: str = Field(default="Policy rule violation detected.")
+    enabled: bool = Field(default=True)
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+class Policy(BaseModel):
+    """A collection of security rules governing agent executions, delegations, and tool access."""
+    
+    policy_id: str = Field(default_factory=lambda: generate_id("pol"))
+    name: str = Field(..., description="Policy name")
+    description: str = Field(default="")
+    version: str = Field(default="1.0.0")
+    rules: List[PolicyRule] = Field(default_factory=list)
+    enabled: bool = Field(default=True)
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+

actshield/posture/__init__.py

@@ -0,0 +1,26 @@
+"""ActShield Posture Engine Package (Phase 9)."""
+
+from actshield.posture.posture_models import (
+    FindingSeverity,
+    PostureDiff,
+    PostureDimensionMetrics,
+    PostureFinding,
+    PostureRating,
+    SecurityPostureSnapshot,
+)
+from actshield.posture.posture_rules import PostureRuleEvaluator
+from actshield.posture.posture_engine import PostureDiffEngine, PostureEngine
+
+__all__ = [
+    "FindingSeverity",
+    "PostureDiff",
+    "PostureDimensionMetrics",
+    "PostureFinding",
+    "PostureRating",
+    "SecurityPostureSnapshot",
+    "PostureRuleEvaluator",
+    "PostureDiffEngine",
+    "PostureEngine",
+]
+
+

actshield/posture/posture_engine.py

@@ -0,0 +1,186 @@
+"""Posture diffing, metrics calculation, and engine implementation."""
+
+from __future__ import annotations
+
+import statistics
+import time
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+from actshield.posture.posture_models import (
+    FindingSeverity,
+    PostureDiff,
+    PostureDimensionMetrics,
+    PostureFinding,
+    PostureRating,
+    SecurityPostureSnapshot,
+)
+from actshield.posture.posture_rules import PostureRuleEvaluator
+
+
+class PostureDiffEngine:
+    """Computes explainable diffs between two security posture snapshots."""
+
+    @staticmethod
+    def diff(before: SecurityPostureSnapshot, after: SecurityPostureSnapshot) -> PostureDiff:
+        score_change = round(after.security_score - before.security_score, 1)
+        rating_transition = f"{before.rating.value} -> {after.rating.value}"
+
+        before_fnd_titles = {f.title for f in before.findings}
+        new_findings = [f for f in after.findings if f.title not in before_fnd_titles]
+        after_fnd_titles = {f.title for f in after.findings}
+        resolved_findings = [f.title for f in before.findings if f.title not in after_fnd_titles]
+
+        # Calculate metric deltas
+        metric_deltas: Dict[str, Any] = {}
+        before_dict = before.metrics.model_dump()
+        after_dict = after.metrics.model_dump()
+        for k in before_dict:
+            b_val = before_dict[k]
+            a_val = after_dict[k]
+            if isinstance(b_val, (int, float)) and isinstance(a_val, (int, float)):
+                metric_deltas[k] = {
+                    "before": b_val,
+                    "after": a_val,
+                    "delta": round(a_val - b_val, 2),
+                }
+
+        if score_change > 0:
+            summary = f"Security posture improved by +{score_change} pts ({rating_transition}). Resolved {len(resolved_findings)} finding(s)."
+        elif score_change < 0:
+            summary = f"Security posture degraded by {score_change} pts ({rating_transition}). Discovered {len(new_findings)} new finding(s)."
+        else:
+            summary = f"Security posture remained stable at {after.security_score} pts ({rating_transition})."
+
+        return PostureDiff(
+            before_snapshot_id=before.snapshot_id,
+            after_snapshot_id=after.snapshot_id,
+            score_change=score_change,
+            rating_transition=rating_transition,
+            new_findings=new_findings,
+            resolved_findings=resolved_findings,
+            metric_deltas=metric_deltas,
+            summary=summary,
+        )
+
+
+class PostureEngine:
+    """Derives measurable posture snapshots from live runtime state."""
+
+    def __init__(self, guard: Optional[Any] = None) -> None:
+        self.guard = guard
+        self.snapshots: List[SecurityPostureSnapshot] = []
+        self._latencies: List[float] = []
+
+    def evaluate_current_posture(
+        self,
+        events: Optional[List[Dict[str, Any]]] = None,
+        regressions: Optional[List[Dict[str, Any]]] = None,
+        incidents: Optional[List[Dict[str, Any]]] = None,
+        agents: Optional[List[Dict[str, Any]]] = None,
+        environment: str = "production",
+    ) -> SecurityPostureSnapshot:
+        """Derive and return the current Security Posture Snapshot."""
+        return self.generate_snapshot(
+            events=events or [],
+            regressions=regressions,
+            incidents=incidents,
+            agents=agents,
+            environment=environment,
+        )
+
+    def record_latency(self, latency_ms: float) -> None:
+        """Record enforcement latency measurement."""
+
+        self._latencies.append(latency_ms)
+        if len(self._latencies) > 5000:
+            self._latencies.pop(0)
+
+    def compute_metrics(
+        self,
+        events: List[Dict[str, Any]],
+        regressions: Optional[List[Dict[str, Any]]] = None,
+        incidents: Optional[List[Dict[str, Any]]] = None,
+        agents: Optional[List[Dict[str, Any]]] = None,
+    ) -> PostureDimensionMetrics:
+        """Derive dimension metrics from real event logs and state."""
+        regressions = regressions or []
+        incidents = incidents or []
+        agents = agents or []
+
+        unauthorized_attempts = sum(1 for e in events if e.get("decision") in ("BLOCK", "REVOKE"))
+        actual_unauthorized = sum(1 for e in events if e.get("decision") == "ALLOW" and e.get("taint") == "TAINTED" and e.get("resource_sensitivity") in ("HIGH", "CRITICAL"))
+        tainted_reqs = sum(1 for e in events if e.get("taint") in ("TAINTED", "UNTRUSTED") and e.get("tool"))
+        auth_violations = sum(1 for e in events if e.get("authority_violation") or "authority" in str(e.get("reason", "")).lower())
+        intent_violations = sum(1 for e in events if e.get("intent_alignment") in ("VIOLATED", "DRIFTING"))
+        blocked_actions = sum(1 for e in events if e.get("decision") == "BLOCK")
+        hitl_actions = sum(1 for e in events if e.get("decision") in ("HITL", "HUMAN_APPROVAL"))
+        allowed_actions = sum(1 for e in events if e.get("decision") == "ALLOW")
+
+        untrusted_crossings = sum(1 for e in events if e.get("context_source") == "external_mcp" or e.get("taint") == "UNTRUSTED")
+        sensitive_exposures = sum(1 for e in events if e.get("resource_sensitivity") in ("HIGH", "CRITICAL"))
+
+        open_regs = sum(1 for r in regressions if r.get("status", "OPEN") == "OPEN")
+        failed_replays = sum(1 for r in regressions if r.get("replay_result") == "FAIL" or r.get("secured_replay_passed") is False)
+        off_failures = sum(1 for r in regressions if r.get("bypass_detected") is True)
+
+        high_risk_agents = sum(1 for a in agents if str(a.get("trust_level", "")).lower() in ("low", "untrusted"))
+
+        # Latencies
+        mean_lat = round(statistics.mean(self._latencies), 2) if self._latencies else 0.45
+        p95_lat = round(statistics.quantiles(self._latencies, n=20)[18], 2) if len(self._latencies) >= 20 else (mean_lat * 1.4)
+
+        return PostureDimensionMetrics(
+            unauthorized_access_attempts=unauthorized_attempts,
+            actual_unauthorized_executions=actual_unauthorized,
+            tainted_sensitive_requests=tainted_reqs,
+            authority_violations=auth_violations,
+            intent_violations=intent_violations,
+            blocked_actions=blocked_actions,
+            hitl_actions=hitl_actions,
+            allowed_actions=allowed_actions,
+            high_risk_agents_count=high_risk_agents,
+            untrusted_context_crossings=untrusted_crossings,
+            sensitive_resource_exposures=sensitive_exposures,
+            open_regressions=open_regs,
+            failed_secured_replays=failed_replays,
+            offensive_validation_failures=off_failures,
+            ai_secura_availability_pct=100.0,
+            apiris_availability_pct=100.0,
+            policy_engine_availability_pct=100.0,
+            mean_enforcement_latency_ms=mean_lat,
+            p95_enforcement_latency_ms=p95_lat,
+        )
+
+    def generate_snapshot(
+        self,
+        events: List[Dict[str, Any]],
+        regressions: Optional[List[Dict[str, Any]]] = None,
+        incidents: Optional[List[Dict[str, Any]]] = None,
+        agents: Optional[List[Dict[str, Any]]] = None,
+        environment: str = "production",
+    ) -> SecurityPostureSnapshot:
+        """Create and store a full security posture snapshot."""
+        metrics = self.compute_metrics(events, regressions, incidents, agents)
+        score, rating, findings = PostureRuleEvaluator.evaluate(metrics)
+
+        snapshot = SecurityPostureSnapshot(
+            rating=rating,
+            security_score=score,
+            metrics=metrics,
+            findings=findings,
+            active_incidents_count=len(incidents or []),
+            total_events_evaluated=len(events),
+            environment=environment,
+        )
+        self.snapshots.append(snapshot)
+        return snapshot
+
+    def get_latest_snapshot(self) -> Optional[SecurityPostureSnapshot]:
+        return self.snapshots[-1] if self.snapshots else None
+
+    def diff_latest(self) -> Optional[PostureDiff]:
+        if len(self.snapshots) < 2:
+            return None
+        return PostureDiffEngine.diff(self.snapshots[-2], self.snapshots[-1])
+