actshield 0.9.0__py3-none-any.whl

actshield/forensics/authority_graph.py

@@ -0,0 +1,186 @@
+"""Authority graph — builds and queries the agent authority/delegation graph.
+
+Read-only. Does not grant or modify any authority.
+Uses data already present in delegation_registry and agent_registry.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Dict, List, Optional, Set
+from actshield.forensics.models import AuthorityRelationship, DelegationRelationship
+
+if TYPE_CHECKING:
+    from actshield.client import ActShield
+
+
+class AuthorityGraph:
+    """Directed authority graph built from the ActShield delegation registry.
+
+    Nodes  = agent_ids
+    Edges  = delegation records (delegator → delegate, labelled with capabilities)
+
+    Never grants authority — read-only projection of existing security state.
+    """
+
+    def __init__(self) -> None:
+        # adjacency: delegator_id → list of DelegationRelationship
+        self._outgoing: Dict[str, List[DelegationRelationship]] = {}
+        # reverse: delegate_id → list of DelegationRelationship
+        self._incoming: Dict[str, List[DelegationRelationship]] = {}
+
+    # ------------------------------------------------------------------
+    # Build
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def from_guard(cls, guard: "ActShield") -> "AuthorityGraph":
+        """Construct graph from an ActShield instance's delegation registry."""
+        g = cls()
+        for dlg in guard.delegation_registry.values():
+            rel = DelegationRelationship(
+                delegation_id=dlg.delegation_id,
+                delegator_agent_id=dlg.delegator_agent_id,
+                delegate_agent_id=dlg.delegate_agent_id,
+                granted_capabilities=list(dlg.authority_grant.granted_capabilities),
+                depth=dlg.depth,
+                parent_delegation_id=dlg.parent_delegation_id,
+                task_id=dlg.task_id,
+                trace_id=dlg.trace_id,
+                status=dlg.status,
+                timestamp=dlg.created_at,
+            )
+            g._add_edge(rel)
+        return g
+
+    def add_delegation(self, rel: DelegationRelationship) -> None:
+        """Add a delegation relationship to the graph."""
+        self._add_edge(rel)
+
+    def _add_edge(self, rel: DelegationRelationship) -> None:
+        src = rel.delegator_agent_id
+        dst = rel.delegate_agent_id
+        self._outgoing.setdefault(src, []).append(rel)
+        self._incoming.setdefault(dst, []).append(rel)
+
+    # ------------------------------------------------------------------
+    # Queries
+    # ------------------------------------------------------------------
+
+    def get_delegations_from(self, agent_id: str) -> List[DelegationRelationship]:
+        """Return all delegations initiated by agent_id."""
+        return list(self._outgoing.get(agent_id, []))
+
+    def get_delegations_to(self, agent_id: str) -> List[DelegationRelationship]:
+        """Return all delegations received by agent_id."""
+        return list(self._incoming.get(agent_id, []))
+
+    def get_authority_relationships(
+        self, agent_id: str
+    ) -> List[AuthorityRelationship]:
+        """Return AuthorityRelationship objects where agent_id is delegator or delegate."""
+        rels: List[AuthorityRelationship] = []
+        for dlg in self.get_delegations_from(agent_id):
+            rels.append(
+                AuthorityRelationship(
+                    source_agent_id=dlg.delegator_agent_id,
+                    target_agent_id=dlg.delegate_agent_id,
+                    capabilities=dlg.granted_capabilities,
+                    delegation_id=dlg.delegation_id,
+                    task_id=dlg.task_id,
+                    trace_id=dlg.trace_id,
+                    depth=dlg.depth,
+                    timestamp=dlg.timestamp,
+                    status=dlg.status,
+                )
+            )
+        for dlg in self.get_delegations_to(agent_id):
+            rels.append(
+                AuthorityRelationship(
+                    source_agent_id=dlg.delegator_agent_id,
+                    target_agent_id=dlg.delegate_agent_id,
+                    capabilities=dlg.granted_capabilities,
+                    delegation_id=dlg.delegation_id,
+                    task_id=dlg.task_id,
+                    trace_id=dlg.trace_id,
+                    depth=dlg.depth,
+                    timestamp=dlg.timestamp,
+                    status=dlg.status,
+                )
+            )
+        return rels
+
+    def get_delegation_chain(self, agent_id: str) -> List[DelegationRelationship]:
+        """Walk the delegation chain from root to agent_id (recursive)."""
+        chain: List[DelegationRelationship] = []
+        visited: Set[str] = set()
+        self._walk_up(agent_id, chain, visited)
+        chain.sort(key=lambda r: r.depth)
+        return chain
+
+    def _walk_up(
+        self,
+        agent_id: str,
+        chain: List[DelegationRelationship],
+        visited: Set[str],
+    ) -> None:
+        if agent_id in visited:
+            return
+        visited.add(agent_id)
+        for rel in self.get_delegations_to(agent_id):
+            chain.append(rel)
+            self._walk_up(rel.delegator_agent_id, chain, visited)
+
+    def get_all_delegatees(self, agent_id: str) -> List[str]:
+        """Return all agents that agent_id has (directly or transitively) delegated to."""
+        result: List[str] = []
+        visited: Set[str] = set()
+        self._walk_down(agent_id, result, visited)
+        return result
+
+    def _walk_down(
+        self, agent_id: str, result: List[str], visited: Set[str]
+    ) -> None:
+        if agent_id in visited:
+            return
+        visited.add(agent_id)
+        for rel in self.get_delegations_from(agent_id):
+            dst = rel.delegate_agent_id
+            if dst not in result:
+                result.append(dst)
+            self._walk_down(dst, result, visited)
+
+    def get_delegated_capabilities(self, agent_id: str) -> List[str]:
+        """Return all capabilities delegated TO agent_id (most recent active delegation)."""
+        delegations = self.get_delegations_to(agent_id)
+        if not delegations:
+            return []
+        # Prefer active ones, fall back to completed
+        active = [d for d in delegations if d.status == "active"]
+        source = active if active else delegations
+        caps: Set[str] = set()
+        for d in source:
+            caps.update(d.granted_capabilities)
+        return sorted(caps)
+
+    def get_all_agents(self) -> List[str]:
+        """Return all agent IDs present in the graph."""
+        agents: Set[str] = set()
+        agents.update(self._outgoing.keys())
+        agents.update(self._incoming.keys())
+        return sorted(agents)
+
+    def to_dict(self) -> dict:
+        """Serializable representation of the authority graph."""
+        edges = []
+        seen: Set[str] = set()
+        for rels in self._outgoing.values():
+            for rel in rels:
+                if rel.delegation_id not in seen:
+                    seen.add(rel.delegation_id)
+                    edges.append(rel.model_dump(mode="json"))
+        return {
+            "nodes": self.get_all_agents(),
+            "edges": edges,
+        }
+
+

actshield/forensics/delegation_graph.py

@@ -0,0 +1,119 @@
+"""Effective access calculator — deterministic, never uses AI.
+
+Calculates:
+    effective_access = declared_capabilities
+                     + valid_delegated_capabilities
+                     - explicit_restrictions
+
+Uses existing ActShield:
+    - agent_registry (declared capabilities)
+    - delegation_registry (delegated capabilities)
+    - tool_registry (required capabilities per tool)
+    - authority containment logic
+
+Does NOT use AI Secura or APIRIS for access determination.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Dict, List, Set
+
+if TYPE_CHECKING:
+    from actshield.client import ActShield
+
+
+class EffectiveAccessCalculator:
+    """Deterministic calculation of effective capabilities and reachable resources.
+
+    effective_access = declared_capabilities
+                     + valid_delegated_capabilities
+                     - explicit_restrictions
+
+    Monotonic authority containment is preserved — a delegated agent can
+    never receive more authority than the delegator holds.
+    """
+
+    def __init__(self, guard: "ActShield") -> None:
+        self._guard = guard
+
+    def get_effective_capabilities(self, agent_id: str) -> List[str]:
+        """Return the union of declared + delegated capabilities for agent_id."""
+        agent = self._guard.agent_registry.get(agent_id)
+        declared: Set[str] = set(agent.capability_names()) if agent else set()
+
+        delegated: Set[str] = set()
+        for dlg in self._guard.delegation_registry.values():
+            if dlg.delegate_agent_id == agent_id and dlg.status in ("active", "completed"):
+                delegated.update(dlg.authority_grant.granted_capabilities)
+
+        return sorted(declared | delegated)
+
+    def get_declared_capabilities(self, agent_id: str) -> List[str]:
+        agent = self._guard.agent_registry.get(agent_id)
+        return agent.capability_names() if agent else []
+
+    def get_delegated_capabilities(self, agent_id: str) -> List[str]:
+        caps: Set[str] = set()
+        for dlg in self._guard.delegation_registry.values():
+            if dlg.delegate_agent_id == agent_id and dlg.status in ("active", "completed"):
+                caps.update(dlg.authority_grant.granted_capabilities)
+        return sorted(caps)
+
+    def get_reachable_tools(self, agent_id: str) -> List[str]:
+        """Return tools this agent can invoke based on effective capabilities."""
+        effective = set(self.get_effective_capabilities(agent_id))
+        reachable = []
+        for tool_def in self._guard.tool_registry.values():
+            required = set(tool_def.required_capabilities)
+            if not required or required.issubset(effective):
+                reachable.append(tool_def.name)
+        return sorted(reachable)
+
+    def get_reachable_resources(self, agent_id: str) -> List[str]:
+        """Return resources this agent can reach via effective capabilities."""
+        reachable_tools = set(self.get_reachable_tools(agent_id))
+        resources: List[str] = []
+        seen: Set[str] = set()
+        for tool_def in self._guard.tool_registry.values():
+            if tool_def.name in reachable_tools:
+                for resource in tool_def.target_resources:
+                    if resource.name not in seen:
+                        seen.add(resource.name)
+                        resources.append(resource.name)
+        return sorted(resources)
+
+    def can_access_tool(self, agent_id: str, tool_name: str) -> bool:
+        """Check if agent has effective permission to invoke a named tool."""
+        tool_def = self._get_tool(tool_name)
+        if tool_def is None:
+            return False
+        effective = set(self.get_effective_capabilities(agent_id))
+        required = set(tool_def.required_capabilities)
+        return not required or required.issubset(effective)
+
+    def can_access_resource(self, agent_id: str, resource_name: str) -> bool:
+        """Check if agent has effective permission to reach a named resource."""
+        return resource_name in self.get_reachable_resources(agent_id)
+
+    def build_access_matrix(
+        self,
+        agent_ids: List[str],
+        resource_names: List[str],
+    ) -> Dict[str, Dict[str, bool]]:
+        """Build effective-permission matrix: agent × resource → bool."""
+        matrix: Dict[str, Dict[str, bool]] = {}
+        for agent_id in agent_ids:
+            matrix[agent_id] = {}
+            for resource_name in resource_names:
+                matrix[agent_id][resource_name] = self.can_access_resource(
+                    agent_id, resource_name
+                )
+        return matrix
+
+    def _get_tool(self, tool_name: str):
+        for tool_def in self._guard.tool_registry.values():
+            if tool_def.name == tool_name:
+                return tool_def
+        return None
+
+

actshield/forensics/explanation.py

@@ -0,0 +1,254 @@
+"""Deterministic forensic explainer — assembles evidence-backed explanations.
+
+The explanation is assembled from ACTUAL recorded evidence.
+No LLM is called. No AI invents the explanation.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+from actshield.forensics.models import (
+    AccessDecision,
+    AttackForensicReport,
+    ForensicExplanation,
+    ForensicIncident,
+    IncidentSeverity,
+    IncidentStatus,
+    IncidentType,
+)
+
+if TYPE_CHECKING:
+    from actshield.forensics.service import ForensicService
+
+
+class ForensicExplainer:
+    """Builds deterministic forensic explanations from recorded evidence.
+
+    Source of truth chain:
+      SecurityDecision → structured_explanation → authority_containment
+      → intent_alignment → risk_breakdown + SecurityAnalysisEvidence
+    """
+
+    def __init__(self, service: "ForensicService") -> None:
+        self._svc = service
+
+    def explain_decision(
+        self,
+        event_id: Optional[str] = None,
+        trace_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        tool_name: Optional[str] = None,
+        decision_dict: Optional[Dict[str, Any]] = None,
+    ) -> ForensicExplanation:
+        """Build a forensic explanation from a stored security decision.
+
+        Falls back to the decision_dict if no storage record is found.
+        """
+        resolved_decision: Dict[str, Any] = {}
+
+        # Try to pull from storage by trace_id
+        if trace_id and self._svc._guard.storage:
+            stored = self._svc._guard.storage.get_decisions(trace_id=trace_id, limit=1)
+            if stored:
+                resolved_decision = stored[0]
+
+        # Merge with provided dict
+        if decision_dict:
+            resolved_decision.update(decision_dict)
+
+        structured = resolved_decision.get("details_json") or {}
+        if isinstance(structured, str):
+            import json
+            try:
+                structured = json.loads(structured)
+            except Exception:
+                structured = {}
+
+        se = structured.get("structured_explanation", {})
+        auth = structured.get("authority_containment", {})
+        intent = structured.get("intent_alignment", {})
+
+        # Map decision action to AccessDecision
+        action_str = resolved_decision.get("action", "UNKNOWN").upper()
+        try:
+            policy_decision = AccessDecision(action_str)
+        except ValueError:
+            policy_decision = AccessDecision.UNKNOWN
+
+        # Influencing context — from the access graph
+        attempts = self._svc.access_graph.get_agent_attempts(agent_id or "")
+        related = [a for a in attempts if a.tool_name == (tool_name or "")]
+        context_sources = []
+        context_ids = []
+        taint_state = "CLEAN"
+        if related:
+            latest = related[-1]
+            context_ids = latest.context_ids
+            taint_state = latest.taint_state
+
+        # Context sources from structured explanation
+        context_sources = se.get("context_sources", [])
+
+        # Delegated authority
+        delegated_caps = se.get("delegated_capabilities", [])
+        if isinstance(delegated_caps, str):
+            delegated_caps = [delegated_caps] if delegated_caps else []
+
+        effective_authority = "GRANTED" if auth.get("contained", False) else "DENIED"
+
+        # AI/APIRIS summaries
+        ai_summary = None
+        apiris_summary = None
+        if agent_id:
+            for attempt in self._svc.access_graph.get_agent_attempts(agent_id):
+                if attempt.tool_name == (tool_name or ""):
+                    # Check access graph for security evidence references
+                    pass
+
+        return ForensicExplanation(
+            event_id=event_id,
+            trace_id=trace_id or resolved_decision.get("trace_id"),
+            agent_id=agent_id or se.get("agent", ""),
+            tool_name=tool_name or se.get("requested_tool", ""),
+            resource_name=se.get("sensitive_sink"),
+            resource_sensitivity=se.get("sink_sensitivity", "UNKNOWN"),
+            original_intent=intent.get("original_intent", "Unspecified"),
+            influencing_context_sources=context_sources,
+            influencing_context_ids=context_ids,
+            context_trust="UNTRUSTED" if taint_state == "TAINTED" else "TRUSTED",
+            taint_state=taint_state,
+            delegated_authority=delegated_caps,
+            requested_capability=(
+                se.get("required_capabilities", [None])[0]
+                if isinstance(se.get("required_capabilities"), list)
+                else se.get("required_capabilities")
+            ),
+            effective_authority=effective_authority,
+            policy_decision=policy_decision,
+            policy_reason_code=resolved_decision.get("reason_code", ""),
+            policy_explanation=resolved_decision.get("explanation", ""),
+            ai_secura_summary=ai_summary,
+            apiris_summary=apiris_summary,
+            tool_executed=False,
+            execution_count=0,
+        )
+
+    def explain_attack(
+        self, attack_id: str
+    ) -> Optional[AttackForensicReport]:
+        """Build an AttackForensicReport from Phase 5 evidence."""
+        result = self._svc._attack_results.get(attack_id)
+        if result is None:
+            return None
+
+        ev = result.security_evidence
+        lineage = result.mutation_lineage
+
+        # Reachable resources for acting agent
+        agent_id = ev.acting_agent if ev else ""
+        reachable = []
+        if agent_id and self._svc._calculator:
+            reachable = self._svc._calculator.get_reachable_resources(agent_id)
+
+        ai_summary = None
+        apiris_summary = None
+        if ev:
+            if ev.ai_analysis and not ev.ai_unavailable:
+                ai_summary = str(
+                    ev.ai_analysis.get("threat_classification") or
+                    ev.ai_analysis.get("security_level") or ""
+                )
+            if ev.apiris_analysis and not ev.apiris_unavailable:
+                apiris_summary = str(
+                    ev.apiris_analysis.get("risk_level") or
+                    ev.apiris_analysis.get("classification") or ""
+                )
+
+        try:
+            policy_dec = AccessDecision(result.actual_decision.upper())
+        except ValueError:
+            policy_dec = AccessDecision.UNKNOWN
+
+        return AttackForensicReport(
+            attack_id=attack_id,
+            campaign_id=result.campaign_id,
+            attack_type=result.attack_type.value,
+            target=result.target,
+            entry_point=result.entry_point,
+            agent_id=agent_id,
+            trace_id=result.trace_id,
+            original_intent=ev.task_intent if ev else "",
+            mutation_lineage=lineage,
+            adaptive_iteration=getattr(result, "adaptive_iteration", 0),
+            influencing_contexts=ev.context_ids if ev else [],
+            context_trust="UNTRUSTED" if (ev and ev.taint_state == "TAINTED") else "TRUSTED",
+            taint_state=ev.taint_state if ev else "UNKNOWN",
+            delegated_capabilities=ev.delegated_capabilities if ev else [],
+            requested_capability=ev.requested_capability if ev else None,
+            effective_capabilities=ev.delegated_capabilities if ev else [],
+            authority_contained=ev.authority_contained if ev else True,
+            resource_name=None,
+            apiris_summary=apiris_summary,
+            ai_secura_summary=ai_summary,
+            risk_score=ev.risk_score if ev else 0.0,
+            policy_decision=policy_dec,
+            policy_reason_code=ev.policy_reason_code if ev else "",
+            policy_explanation=ev.policy_explanation if ev else "",
+            tool_executed=result.actual_execution,
+            execution_count=result.execution_evidence.execution_count,
+            sensitive_db_calls=result.execution_evidence.sensitive_db_calls,
+            actual_access=result.actual_execution,
+            reachable_resources=reachable,
+            bypassed=result.bypassed,
+            expected_decision=result.expected_decision,
+            actual_decision=result.actual_decision,
+            regression_status=(
+                "REGRESSION_CREATED" if result.bypassed else "NONE"
+            ),
+        )
+
+    def classify_incident(
+        self, attempt: "ForensicExplanation"
+    ) -> IncidentType:
+        """Classify incident type deterministically from the explanation."""
+        if attempt.bypass_detected:
+            return IncidentType.BYPASS_DETECTED
+        reason = attempt.policy_reason_code
+        if "TAINTED" in reason:
+            return IncidentType.TAINT_PROPAGATION
+        if "AUTHORITY" in reason or "DELEGATION" in reason:
+            return IncidentType.AUTHORITY_ESCALATION
+        if "CAPABILITY" in reason or "MISSING" in reason:
+            return IncidentType.CAPABILITY_VIOLATION
+        if "INTENT" in reason:
+            return IncidentType.INTENT_VIOLATION
+        if "UNTRUSTED" in reason:
+            return IncidentType.UNTRUSTED_SENSITIVE_ACCESS
+        return IncidentType.GENERIC
+
+    def build_incident(
+        self, explanation: ForensicExplanation
+    ) -> ForensicIncident:
+        """Build a ForensicIncident from an explanation (uses IDs, no duplication)."""
+        severity = (
+            IncidentSeverity.CRITICAL
+            if explanation.resource_sensitivity == "CRITICAL"
+            else IncidentSeverity.HIGH
+            if explanation.policy_decision == AccessDecision.BLOCK
+            else IncidentSeverity.MEDIUM
+        )
+        return ForensicIncident(
+            incident_type=self.classify_incident(explanation),
+            severity=severity,
+            agent_id=explanation.agent_id,
+            resource_name=explanation.resource_name,
+            tool_name=explanation.tool_name,
+            decision=explanation.policy_decision,
+            executed=explanation.tool_executed,
+            trace_id=explanation.trace_id,
+            attack_id=explanation.bypass_attack_id,
+            status=IncidentStatus.CONTAINED,
+            description=explanation.policy_explanation,
+        )
+