actshield 0.9.0__py3-none-any.whl

actshield/config.py

@@ -0,0 +1,88 @@
+"""Configuration module for ActShield SDK."""
+
+import re
+from typing import Any, Callable, Dict, List, Optional, Pattern
+from pydantic import BaseModel, Field
+
+
+DEFAULT_SECRET_PATTERNS: List[Pattern[str]] = [
+    re.compile(r"(?i)(bearer\s+)[a-zA-Z0-9_\-\.]{15,}"),
+    re.compile(r"(?i)(api[_\-]?key|secret|token|password|passwd|auth[_\-]?token)\s*[:=]\s*['\"]?([a-zA-Z0-9_\-\.]{8,})['\"]?"),
+    re.compile(r"(?i)(sk-[a-zA-Z0-9]{20,})"),
+    re.compile(r"(?i)(ghp_[a-zA-Z0-9]{36})"),
+    re.compile(r"(?i)(xox[baprs]-[a-zA-Z0-9\-]{10,})"),
+]
+
+SENSITIVE_KEY_NAMES = {
+    "api_key", "apikey", "secret", "password", "passwd", "token", 
+    "access_token", "auth_token", "private_key", "secret_key", 
+    "credentials", "authorization"
+}
+
+
+def default_redact_function(data: Any) -> Any:
+    """Recursively redacts secrets and sensitive key values."""
+    if isinstance(data, str):
+        result = data
+        for pattern in DEFAULT_SECRET_PATTERNS:
+            result = pattern.sub(r"\1[REDACTED]", result)
+        return result
+    elif isinstance(data, dict):
+        redacted_dict: Dict[str, Any] = {}
+        for k, v in data.items():
+            if str(k).lower() in SENSITIVE_KEY_NAMES:
+                redacted_dict[k] = "[REDACTED]"
+            else:
+                redacted_dict[k] = default_redact_function(v)
+        return redacted_dict
+    elif isinstance(data, list):
+        return [default_redact_function(item) for item in data]
+    elif isinstance(data, tuple):
+        return tuple(default_redact_function(item) for item in data)
+    return data
+
+
+class ActShieldConfig(BaseModel):
+    """Runtime configuration for actshield."""
+    
+    app_name: str = Field(default="ActShield", description="Application or service name")
+    environment: str = Field(default="production", description="Runtime environment (development, staging, production)")
+    enforcement_mode: str = Field(default="STRICT", description="Control plane enforcement mode (STRICT, MONITOR, AUDIT)")
+    enforce_monotonic_delegation: bool = Field(
+
+        default=True,
+        description="Whether an agent is strictly forbidden from delegating authority it was not granted"
+    )
+    block_tainted_sink_access: bool = Field(
+        default=True,
+        description="Whether tainted untrusted context is blocked from invoking critical sensitive tools"
+    )
+    default_risk_threshold: float = Field(
+        default=0.7,
+        ge=0.0,
+        le=1.0,
+        description="Risk score above which actions are blocked or require human approval"
+    )
+    redact_secrets: bool = Field(
+        default=True,
+        description="Whether to sanitize secret patterns from emitted events, context, and trace payloads"
+    )
+    custom_redactor: Optional[Callable[[Any], Any]] = Field(
+        default=None,
+        description="Custom redaction callable if specified"
+    )
+
+    def sanitize(self, data: Any) -> Any:
+        """Sanitize data using configured redactor."""
+        if not self.redact_secrets:
+            return data
+        if self.custom_redactor:
+            return self.custom_redactor(data)
+        return default_redact_function(data)
+
+
+# Backward compatibility alias
+AgentGuardConfig = ActShieldConfig
+
+
+

actshield/context/__init__.py

@@ -0,0 +1,14 @@
+"""Context, Provenance, and Taint tracking package."""
+
+from actshield.context.context import Context
+from actshield.context.provenance import ContextSource, Provenance, ProvenanceHop
+from actshield.context.taint import TaintState
+
+__all__ = [
+    "Context",
+    "ContextSource",
+    "Provenance",
+    "ProvenanceHop",
+    "TaintState",
+]
+

actshield/context/context.py

@@ -0,0 +1,161 @@
+"""Context container tracking data lineage, provenance, and taint state."""
+
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+
+from actshield.context.provenance import ContextSource, ContextTrustLevel, Provenance
+from actshield.context.taint import TaintState
+from actshield.tracing.correlation import generate_id
+from actshield.tracing.events import EventType
+
+if TYPE_CHECKING:
+    from actshield.client import ActShield
+
+
+class Context(BaseModel):
+    """Context and data lineage container tracked by actshield."""
+    
+    context_id: str = Field(default_factory=lambda: generate_id("ctx"), description="Unique context ID")
+    data: Any = Field(default=None, description="Payload data content or summary")
+    source: ContextSource = Field(default=ContextSource.USER, description="Original source")
+    source_type: str = Field(default="text", description="MIME type or semantic type")
+    source_uri: Optional[str] = Field(default=None, description="URI or locator of context source")
+    trust_level: str = Field(default="trusted", description="Trust level assigned at ingestion ('trusted', 'untrusted', 'verified')")
+    taint_state: TaintState = Field(default=TaintState.CLEAN, description="Current taint classification ('CLEAN', 'UNTRUSTED', 'TAINTED', 'UNKNOWN')")
+    
+    # Origin & Lineage
+    originating_event_id: Optional[str] = Field(default=None, description="Originating event ID")
+    originating_agent_id: Optional[str] = Field(default=None, description="Agent that ingested or produced this")
+    current_agent_id: Optional[str] = Field(default=None, description="Agent currently holding this context")
+    parent_context_id: Optional[str] = Field(default=None, description="Parent context if derived")
+    
+    provenance: Provenance = Field(
+        default_factory=Provenance,
+        description="Chronological provenance graph"
+    )
+    
+    timestamp: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="Creation timestamp"
+    )
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Custom metadata tags")
+
+    def propagate(
+        self,
+        to_agent_id: str,
+        action: str = "propagated",
+        new_data: Any = None,
+        taint_override: Optional[TaintState] = None,
+        guard: Optional["ActShield"] = None,
+    ) -> "Context":
+        """Propagate or transform this context to another agent, recording the lineage hop.
+        
+        Taint is strictly preserved across agent hops unless explicitly sanitized.
+        """
+        new_taint = taint_override or self.taint_state
+        new_provenance = self.provenance.model_copy(deep=True)
+        
+        derived_ctx = Context(
+            context_id=generate_id("ctx"),
+            data=new_data if new_data is not None else self.data,
+            source=self.source,
+            source_type=self.source_type,
+            source_uri=self.source_uri,
+            trust_level=self.trust_level,
+            taint_state=new_taint,
+            originating_event_id=self.originating_event_id,
+            originating_agent_id=self.originating_agent_id,
+            current_agent_id=to_agent_id,
+            parent_context_id=self.context_id,
+            provenance=new_provenance,
+            metadata=dict(self.metadata),
+        )
+
+        event_id = None
+        if guard is not None:
+            guard.context_registry[derived_ctx.context_id] = derived_ctx
+            evt = guard.emit_event(
+                event_type=EventType.CONTEXT_PROPAGATED,
+                context_id=derived_ctx.context_id,
+                agent_id=to_agent_id,
+                parent_agent_id=self.current_agent_id,
+                payload={
+                    "parent_context_id": self.context_id,
+                    "taint_state": derived_ctx.taint_state.value,
+                    "action": action,
+                }
+            )
+            event_id = evt.event_id
+
+        derived_ctx.provenance.record_hop(
+            agent_id=to_agent_id,
+            action=action,
+            event_id=event_id,
+            details={"from_agent": self.current_agent_id, "taint": new_taint.value},
+        )
+
+        return derived_ctx
+
+    def sanitize(
+        self,
+        sanitizer_name: str,
+        reason: str,
+        transformed_data: Any = None,
+        new_taint: TaintState = TaintState.CLEAN,
+        guard: Optional["ActShield"] = None,
+    ) -> "Context":
+        """Perform an explicit, auditable sanitization operation on this context artifact."""
+        previous_taint = self.taint_state.value
+        new_provenance = self.provenance.model_copy(deep=True)
+
+        sanitized_ctx = Context(
+            context_id=generate_id("ctx"),
+            data=transformed_data if transformed_data is not None else self.data,
+            source=self.source,
+            source_type=f"sanitized:{self.source_type}",
+            source_uri=self.source_uri,
+            trust_level="verified",
+            taint_state=new_taint,
+            originating_event_id=self.originating_event_id,
+            originating_agent_id=self.originating_agent_id,
+            current_agent_id=self.current_agent_id,
+            parent_context_id=self.context_id,
+            provenance=new_provenance,
+            metadata={
+                **self.metadata,
+                "sanitized_by": sanitizer_name,
+                "sanitization_reason": reason,
+            },
+        )
+
+        event_id = None
+        if guard is not None:
+            guard.context_registry[sanitized_ctx.context_id] = sanitized_ctx
+            evt = guard.emit_event(
+                event_type=EventType.CONTEXT_SANITIZED,
+                context_id=sanitized_ctx.context_id,
+                agent_id=self.current_agent_id,
+                payload={
+                    "source_context_id": self.context_id,
+                    "resulting_context_id": sanitized_ctx.context_id,
+                    "sanitizer_name": sanitizer_name,
+                    "reason": reason,
+                    "previous_taint": previous_taint,
+                    "new_taint": new_taint.value,
+                }
+            )
+            event_id = evt.event_id
+
+        sanitized_ctx.provenance.record_sanitization(
+            sanitizer_name=sanitizer_name,
+            reason=reason,
+            previous_taint=previous_taint,
+            new_taint=new_taint.value,
+            event_id=event_id,
+            details={"source_context_id": self.context_id},
+        )
+
+        return sanitized_ctx
+
+

actshield/context/provenance.py

@@ -0,0 +1,108 @@
+"""Data provenance and lineage tracking models."""
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+
+
+class ContextSource(str, Enum):
+    """Origin sources for context ingested or generated by agents."""
+    USER = "user"
+    EXTERNAL_MCP = "external_mcp"
+    SYSTEM = "system"
+    TOOL_OUTPUT = "tool_output"
+    AGENT_GENERATED = "agent_generated"
+    EXTERNAL_API = "external_api"
+    DATABASE = "database"
+    FILE_SYSTEM = "file_system"
+
+
+class ContextTrustLevel(str, Enum):
+    """Source trust classification (orthogonal to data taint)."""
+    TRUSTED = "trusted"
+    UNTRUSTED = "untrusted"
+    VERIFIED = "verified"
+    UNKNOWN = "unknown"
+
+
+class ProvenanceHop(BaseModel):
+    """An individual hop or transformation in the lifecycle of a context artifact."""
+    agent_id: Optional[str] = Field(default=None, description="Agent performing the hop/transformation")
+    action: str = Field(..., description="Action taken (e.g. 'received', 'transformed', 'delegated', 'injected')")
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    event_id: Optional[str] = Field(default=None, description="Event ID correlated with this hop")
+    details: Dict[str, Any] = Field(default_factory=dict)
+
+
+class SanitizationRecord(BaseModel):
+    """Auditable record of an explicit context sanitization transformation."""
+    sanitizer_name: str
+    reason: str
+    previous_taint: str
+    new_taint: str
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    event_id: Optional[str] = None
+    details: Dict[str, Any] = Field(default_factory=dict)
+
+
+class Provenance(BaseModel):
+    """Complete causal history of a piece of context or data."""
+    
+    source: ContextSource = Field(default=ContextSource.USER, description="Original source type")
+    source_uri: Optional[str] = Field(default=None, description="URI or identifier of source (e.g. mcp://weather-server, /var/log)")
+    trust_level: str = Field(default="trusted", description="Trust level of the origin source")
+    originating_event_id: Optional[str] = Field(default=None, description="Initial event ID where context appeared")
+    originating_agent_id: Optional[str] = Field(default=None, description="Initial agent that ingested or produced this context")
+    originating_timestamp: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="Timestamp of origin"
+    )
+    hops: List[ProvenanceHop] = Field(
+        default_factory=list,
+        description="Chronological record of agents and actions touching this context"
+    )
+    sanitizations: List[SanitizationRecord] = Field(
+        default_factory=list,
+        description="Chronological record of auditable sanitizations"
+    )
+
+    def record_hop(
+        self,
+        agent_id: Optional[str],
+        action: str,
+        event_id: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Record an agent transformation or propagation step."""
+        self.hops.append(
+            ProvenanceHop(
+                agent_id=agent_id,
+                action=action,
+                timestamp=datetime.now(timezone.utc),
+                event_id=event_id,
+                details=details or {},
+            )
+        )
+
+    def record_sanitization(
+        self,
+        sanitizer_name: str,
+        reason: str,
+        previous_taint: str,
+        new_taint: str,
+        event_id: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Record an explicit sanitization event."""
+        self.sanitizations.append(
+            SanitizationRecord(
+                sanitizer_name=sanitizer_name,
+                reason=reason,
+                previous_taint=previous_taint,
+                new_taint=new_taint,
+                timestamp=datetime.now(timezone.utc),
+                event_id=event_id,
+                details=details or {},
+            )
+        )

actshield/context/taint.py

@@ -0,0 +1,48 @@
+"""Taint tracking models and propagation rules."""
+
+from enum import Enum
+from typing import List, Optional
+
+
+class TaintState(str, Enum):
+    """Possible taint states for context and data artifacts.
+    
+    Separates origin trust from data taint:
+    - CLEAN / TRUSTED: Verified safe content without malicious or unverified directives.
+    - UNTRUSTED: Originating from an unverified source, but containing clean/benign data.
+    - TAINTED: Ingested or influenced by unverified/adversarial prompt injections or unauthorized directives.
+    - UNKNOWN: Unclassified context.
+    """
+    CLEAN = "CLEAN"
+    TRUSTED = "TRUSTED"  # Backward compatibility alias for CLEAN
+    UNTRUSTED = "UNTRUSTED"
+    TAINTED = "TAINTED"
+    UNKNOWN = "UNKNOWN"
+
+    @property
+    def is_safe(self) -> bool:
+        """Indicates whether this taint level can flow to sensitive sinks without restrictions."""
+        return self in (TaintState.CLEAN, TaintState.TRUSTED)
+
+    @property
+    def is_tainted(self) -> bool:
+        """Indicates whether the data is flagged as carrying untrusted/injected payload."""
+        return self == TaintState.TAINTED
+
+    @classmethod
+    def combine(cls, *states: "TaintState") -> "TaintState":
+        """Combine multiple taint states into a single conservative worst-case taint state."""
+        state_list = [s for s in states if s is not None]
+        if not state_list:
+            return cls.UNKNOWN
+        
+        if cls.TAINTED in state_list:
+            return cls.TAINTED
+        if cls.UNTRUSTED in state_list:
+            return cls.UNTRUSTED
+        if cls.UNKNOWN in state_list:
+            return cls.UNKNOWN
+        if cls.TRUSTED in state_list:
+            return cls.TRUSTED
+        return cls.CLEAN
+

actshield/decisions/decision.py

@@ -0,0 +1,74 @@
+"""Security enforcement decision models."""
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+
+from actshield.risk.models import RiskFactorBreakdown, RiskLevel
+from actshield.tracing.correlation import generate_id
+
+
+class DecisionAction(str, Enum):
+    """Deterministic security enforcement actions."""
+    ALLOW = "ALLOW"
+    MONITOR = "MONITOR"
+    HUMAN_APPROVAL = "HUMAN_APPROVAL"
+    QUARANTINE = "QUARANTINE"
+    BLOCK = "BLOCK"
+    REVOKE = "REVOKE"
+
+
+class SecurityDecision(BaseModel):
+    """A deterministic security decision emitted after policy evaluation."""
+    
+    decision_id: str = Field(default_factory=lambda: generate_id("dec"), description="Unique decision ID")
+    action: DecisionAction = Field(..., description="Deterministic enforcement action")
+    risk_level: RiskLevel = Field(default=RiskLevel.LOW, description="Assessed risk level")
+    risk_score: float = Field(default=0.0, ge=0.0, le=1.0, description="Risk score between 0.0 and 1.0")
+    reason_code: str = Field(..., description="Machine-readable reason code")
+    explanation: str = Field(..., description="Human-readable explanation of why the decision was rendered")
+    trace_id: str = Field(..., description="Trace ID for causal correlation")
+    policy_id: Optional[str] = Field(default=None, description="ID of the policy rule that determined this decision")
+    
+    # Causal and structured evaluation details
+    evidence_references: List[str] = Field(
+        default_factory=list,
+        description="References to event_ids, context_ids, or delegation_ids establishing causal evidence"
+    )
+    influencing_context_ids: List[str] = Field(
+        default_factory=list,
+        description="IDs of context artifacts that influenced this execution request"
+    )
+    authority_containment: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Structured validation of requested capability vs delegated authority"
+    )
+    intent_alignment: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Structured evaluation of original user intent vs requested action"
+    )
+    risk_breakdown: Optional[RiskFactorBreakdown] = Field(
+        default=None,
+        description="Explainable breakdown of risk factor dimensions"
+    )
+    structured_explanation: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Structured breakdown for auditing and SIEM reporting"
+    )
+    
+    evaluated_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="UTC timestamp of evaluation"
+    )
+
+    @property
+    def is_allowed(self) -> bool:
+        """Helper to test if execution is permitted to proceed immediately."""
+        return self.action in (DecisionAction.ALLOW, DecisionAction.MONITOR)
+
+    @property
+    def is_blocked(self) -> bool:
+        """Helper to test if execution was blocked or quarantined."""
+        return self.action in (DecisionAction.BLOCK, DecisionAction.QUARANTINE, DecisionAction.REVOKE)
+

actshield/delegation/__init__.py

@@ -0,0 +1,11 @@
+"""Delegation and Authority package."""
+
+from actshield.delegation.authority import AuthorityGrant
+from actshield.delegation.delegation import Delegation, DelegationScope
+
+__all__ = [
+    "AuthorityGrant",
+    "Delegation",
+    "DelegationScope",
+]
+

actshield/delegation/authority.py

@@ -0,0 +1,63 @@
+"""Authority granting and monotonic delegation validation."""
+
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Set
+from pydantic import BaseModel, Field
+
+from actshield.tracing.correlation import generate_id
+
+
+class AuthorityGrant(BaseModel):
+    """Explicit grant of capabilities from a delegator to a delegate."""
+    
+    grant_id: str = Field(default_factory=lambda: generate_id("grnt"))
+    delegator_agent_id: str = Field(..., description="Agent ID yielding authority")
+    delegate_agent_id: str = Field(..., description="Agent ID receiving authority")
+    granted_capabilities: List[str] = Field(
+        default_factory=list,
+        description="Explicit list of capability names granted"
+    )
+    constraints: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Optional execution constraints (e.g. rate_limit, max_cost, valid_until)"
+    )
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="UTC grant creation timestamp"
+    )
+
+    def contains_capability(self, capability_name: str) -> bool:
+        """Verify if a specific capability is covered by this grant."""
+        if "*" in self.granted_capabilities or capability_name in self.granted_capabilities:
+            return True
+        for cap in self.granted_capabilities:
+            if cap.endswith(".*") and capability_name.startswith(cap[:-2]):
+                return True
+        return False
+
+    def validate_monotonic_reduction(
+        self,
+        delegator_available_capabilities: List[str],
+        strict: bool = True,
+    ) -> bool:
+        """Enforce that granted capabilities are a strict subset of delegator available capabilities."""
+        if not strict:
+            return True
+        if "*" in delegator_available_capabilities:
+            return True
+        
+        delegator_set: Set[str] = set(delegator_available_capabilities)
+        for requested_cap in self.granted_capabilities:
+            if requested_cap == "*":
+                return False  # Cannot grant wildcard if delegator doesn't have wildcard
+            if requested_cap not in delegator_set:
+                # Check wildcard prefix
+                matched = False
+                for d_cap in delegator_set:
+                    if d_cap.endswith(".*") and requested_cap.startswith(d_cap[:-2]):
+                        matched = True
+                        break
+                if not matched:
+                    return False
+        return True
+