actshield 0.9.0__py3-none-any.whl

actshield/posture/posture_models.py

@@ -0,0 +1,152 @@
+"""Security Posture Models for ActShield Phase 9.
+
+Defines measurable security posture dimensions, findings, snapshots, and diffs.
+Adheres strictly to the principle: All posture metrics must be explainable and backed by runtime evidence.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+
+from actshield.tracing.correlation import generate_id
+
+
+class PostureRating(str, Enum):
+    """Overall security posture health rating."""
+    HEALTHY = "HEALTHY"
+    ELEVATED_RISK = "ELEVATED_RISK"
+    DEGRADED = "DEGRADED"
+    CRITICAL = "CRITICAL"
+
+
+class FindingSeverity(str, Enum):
+    """Severity classification for posture findings."""
+    LOW = "LOW"
+    MEDIUM = "MEDIUM"
+    HIGH = "HIGH"
+    CRITICAL = "CRITICAL"
+
+
+class PostureFinding(BaseModel):
+    """Discrete, explainable finding pointing to specific runtime evidence."""
+    finding_id: str = Field(default_factory=lambda: generate_id("fnd"))
+    category: str = Field(..., description="Category: e.g. 'authority_violation', 'taint_exposure', 'open_regression'")
+    severity: FindingSeverity = Field(default=FindingSeverity.MEDIUM)
+    title: str = Field(..., description="Short summary of finding")
+    description: str = Field(..., description="Detailed explanation of the issue")
+    affected_entities: List[str] = Field(default_factory=list, description="Agents, tools, or resources involved")
+    evidence_refs: List[str] = Field(default_factory=list, description="Event IDs or trace IDs serving as ground truth")
+    remediation_advice: str = Field(default="", description="Recommended action to resolve")
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+    @property
+    def deduction(self) -> float:
+        if self.severity == FindingSeverity.CRITICAL:
+            return 25.0
+        elif self.severity == FindingSeverity.HIGH:
+            return 15.0
+        elif self.severity == FindingSeverity.MEDIUM:
+            return 5.0
+        return 2.0
+
+    @property
+    def remediation(self) -> str:
+        return self.remediation_advice
+
+
+
+class PostureDimensionMetrics(BaseModel):
+    """Measurable dimensions derived from actual runtime telemetry and forensic evidence."""
+    unauthorized_access_attempts: int = Field(default=0, description="Blocked unauthorized access attempts")
+    actual_unauthorized_executions: int = Field(default=0, description="CRITICAL: Any execution that bypassed policy")
+    tainted_sensitive_requests: int = Field(default=0, description="Requests carrying tainted context to sensitive tools")
+    authority_violations: int = Field(default=0, description="Requests exceeding delegated capability boundaries")
+    intent_violations: int = Field(default=0, description="Actions drifting from declared user task intent")
+    blocked_actions: int = Field(default=0, description="Total actions blocked by deterministic policy")
+    hitl_actions: int = Field(default=0, description="Total actions escalated to Human-In-The-Loop")
+    allowed_actions: int = Field(default=0, description="Total authorized actions executed")
+    high_risk_agents_count: int = Field(default=0, description="Number of agents with LOW trust or active violations")
+    untrusted_context_crossings: int = Field(default=0, description="Untrusted external data ingress events")
+    sensitive_resource_exposures: int = Field(default=0, description="High/Critical resource access attempts")
+    open_regressions: int = Field(default=0, description="Unresolved security regression fixtures")
+    failed_secured_replays: int = Field(default=0, description="Regressions that failed to block on secured replay")
+    offensive_validation_failures: int = Field(default=0, description="Bypasses discovered during offensive validation")
+    
+    # Availability KPIs
+    ai_secura_availability_pct: float = Field(default=100.0, ge=0.0, le=100.0)
+    apiris_availability_pct: float = Field(default=100.0, ge=0.0, le=100.0)
+    policy_engine_availability_pct: float = Field(default=100.0, ge=0.0, le=100.0)
+    
+    # Latency percentiles in milliseconds
+    mean_enforcement_latency_ms: float = Field(default=0.0)
+    p95_enforcement_latency_ms: float = Field(default=0.0)
+
+    @property
+    def threat_prevention_rate(self) -> float:
+        total = self.blocked_actions + self.actual_unauthorized_executions
+        return 1.0 if total == 0 else max(0.0, min(1.0, self.blocked_actions / total))
+
+    @property
+    def boundary_adherence(self) -> float:
+        return 1.0 if self.authority_violations == 0 else max(0.0, 1.0 - (self.authority_violations / 10.0))
+
+    @property
+    def lineage_integrity(self) -> float:
+        return 1.0 if self.tainted_sensitive_requests == 0 else max(0.0, 1.0 - (self.tainted_sensitive_requests / 10.0))
+
+    @property
+    def incident_containment_speed_score(self) -> float:
+        return 100.0
+
+    @property
+    def hygiene_score(self) -> float:
+        return 100.0 if self.open_regressions == 0 else max(0.0, 100.0 - (self.open_regressions * 10.0))
+
+
+
+class SecurityPostureSnapshot(BaseModel):
+    """Time-series snapshot representing the state of security at a point in time."""
+    snapshot_id: str = Field(default_factory=lambda: generate_id("pos_snap"))
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    rating: PostureRating = Field(default=PostureRating.HEALTHY)
+    security_score: float = Field(default=100.0, ge=0.0, le=100.0, description="100.0 = perfect prevention posture")
+    metrics: PostureDimensionMetrics = Field(default_factory=PostureDimensionMetrics)
+    findings: List[PostureFinding] = Field(default_factory=list)
+    active_incidents_count: int = Field(default=0)
+    total_events_evaluated: int = Field(default=0)
+    environment: str = Field(default="production")
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+    @property
+    def overall_score(self) -> float:
+        """Alias for security_score."""
+        return self.security_score
+
+    @property
+    def evaluated_at(self) -> datetime:
+        """Alias for timestamp."""
+        return self.timestamp
+
+    @property
+    def dimensions(self) -> PostureDimensionMetrics:
+        """Alias for metrics."""
+        return self.metrics
+
+
+
+class PostureDiff(BaseModel):
+    """Comparative diff between two posture snapshots."""
+    before_snapshot_id: str
+    after_snapshot_id: str
+    score_change: float
+    rating_transition: str
+    new_findings: List[PostureFinding] = Field(default_factory=list)
+    resolved_findings: List[str] = Field(default_factory=list)
+    metric_deltas: Dict[str, Any] = Field(default_factory=dict)
+    summary: str
+
+

actshield/posture/posture_rules.py

@@ -0,0 +1,137 @@
+"""Posture calculation rules and scoring logic for ActShield Phase 9.
+
+Computes explainable, deterministic security posture score based on concrete evidence.
+Formula:
+- Starts at 100.0 (Perfect prevention & alignment)
+- Deductions are derived strictly from evidence (e.g. actual executions, open regressions, authority violations)
+- Zero arbitrary ML weights.
+"""
+
+from __future__ import annotations
+
+from typing import List, Tuple
+from actshield.posture.posture_models import (
+    FindingSeverity,
+    PostureDimensionMetrics,
+    PostureFinding,
+    PostureRating,
+)
+
+
+class PostureRuleEvaluator:
+    """Evaluates metrics to produce explainable posture score, rating, and discrete findings."""
+
+    @staticmethod
+    def evaluate(metrics: PostureDimensionMetrics) -> Tuple[float, PostureRating, List[PostureFinding]]:
+        score = 100.0
+        findings: List[PostureFinding] = []
+
+        # 1. Critical invariant: Actual unauthorized execution
+        if metrics.actual_unauthorized_executions > 0:
+            deduction = min(50.0, metrics.actual_unauthorized_executions * 25.0)
+            score -= deduction
+            findings.append(PostureFinding(
+                category="unauthorized_execution",
+                severity=FindingSeverity.CRITICAL,
+                title=f"{metrics.actual_unauthorized_executions} Actual Unauthorized Execution(s) Detected",
+                description="Policy boundary was bypassed and a sensitive operation executed.",
+                remediation_advice="Review vulnerable tools, revoke affected agent credentials, and deploy regression fix immediately.",
+            ))
+
+        # 2. Failed secured replays (Unresolved bypasses)
+        if metrics.failed_secured_replays > 0:
+            deduction = min(30.0, metrics.failed_secured_replays * 15.0)
+            score -= deduction
+            findings.append(PostureFinding(
+                category="failed_secured_replay",
+                severity=FindingSeverity.HIGH,
+                title=f"{metrics.failed_secured_replays} Failed Secured Replay(s)",
+                description="Known attack regression failed to block when replayed against secured policy.",
+                remediation_advice="Harden deterministic policy rules for the failing attack scenario.",
+            ))
+
+        # 3. Open regressions
+        if metrics.open_regressions > 0:
+            deduction = min(20.0, metrics.open_regressions * 5.0)
+            score -= deduction
+            findings.append(PostureFinding(
+                category="open_regression",
+                severity=FindingSeverity.HIGH,
+                title=f"{metrics.open_regressions} Open Security Regression(s)",
+                description="Security test cases flagged as open without verified remediation.",
+                remediation_advice="Run regression replay suite and verify all fixtures pass with BLOCK.",
+            ))
+
+        # 4. Tainted sensitive requests
+        if metrics.tainted_sensitive_requests > 0:
+            deduction = min(15.0, metrics.tainted_sensitive_requests * 2.0)
+            score -= deduction
+            findings.append(PostureFinding(
+                category="taint_exposure",
+                severity=FindingSeverity.MEDIUM,
+                title=f"{metrics.tainted_sensitive_requests} Tainted Context Request(s) to Sensitive Sinks",
+                description="Agents attempted to pass untrusted/tainted context to sensitive resources.",
+                remediation_advice="Inspect context provenance chains and verify input sanitization boundaries.",
+            ))
+
+        # 5. Authority violations
+        if metrics.authority_violations > 0:
+            deduction = min(15.0, metrics.authority_violations * 2.0)
+            score -= deduction
+            findings.append(PostureFinding(
+                category="authority_violation",
+                severity=FindingSeverity.MEDIUM,
+                title=f"{metrics.authority_violations} Delegated Authority Violation(s)",
+                description="Sub-agents attempted actions exceeding granted capability envelopes.",
+                remediation_advice="Enforce stricter delegation scopes and depth limits at task handoff.",
+            ))
+
+        # 6. Intent drift / violations
+        if metrics.intent_violations > 0:
+            deduction = min(10.0, metrics.intent_violations * 2.0)
+            score -= deduction
+            findings.append(PostureFinding(
+                category="intent_violation",
+                severity=FindingSeverity.MEDIUM,
+                title=f"{metrics.intent_violations} Task Intent Violation(s)",
+                description="Actions drifted from declared task intent as analyzed by AI Secura.",
+                remediation_advice="Review task definitions and prompt instructions.",
+            ))
+
+        # 7. Availability degradation
+        if metrics.ai_secura_availability_pct < 95.0:
+            score -= 5.0
+            findings.append(PostureFinding(
+                category="availability_degraded",
+                severity=FindingSeverity.LOW,
+                title=f"AI Secura Availability Low ({metrics.ai_secura_availability_pct:.1f}%)",
+                description="AI Secura reasoning service experienced downtime. Deterministic fallback active.",
+                remediation_advice="Check LLM endpoint health and adapter timeouts.",
+            ))
+
+        if metrics.policy_engine_availability_pct < 100.0:
+            score -= 15.0
+            findings.append(PostureFinding(
+                category="availability_critical",
+                severity=FindingSeverity.HIGH,
+                title="Policy Engine Experienced Interruptions",
+                description="Deterministic policy engine health is below 100%.",
+                remediation_advice="Inspect policy engine logs and persistence locks.",
+            ))
+
+        # Clamp score between 0.0 and 100.0
+        final_score = max(0.0, min(100.0, round(score, 1)))
+
+        # Determine rating
+        if final_score >= 90.0:
+            rating = PostureRating.HEALTHY
+        elif final_score >= 75.0:
+            rating = PostureRating.ELEVATED_RISK
+        elif final_score >= 50.0:
+            rating = PostureRating.DEGRADED
+        else:
+            rating = PostureRating.CRITICAL
+
+        return final_score, rating, findings
+
+

actshield/providers/__init__.py

@@ -0,0 +1,32 @@
+"""
+ActShield Security AI Providers
+================================
+Modular intelligence providers with swappable backends and automatic failover.
+"""
+from actshield.providers.base import AnalysisResult, HealthReport, SecurityAIProvider
+from actshield.providers.registry import (
+    ProviderRegistry,
+    get_default_registry,
+    reset_default_registry,
+)
+from actshield.providers.ollama_provider import OllamaProvider
+from actshield.providers.openai_provider import OpenAIProvider
+from actshield.providers.gemini_provider import GeminiProvider
+from actshield.providers.anthropic_provider import AnthropicProvider
+from actshield.providers.null_provider import NullProvider
+
+__all__ = [
+    "SecurityAIProvider",
+    "AnalysisResult",
+    "HealthReport",
+    "ProviderRegistry",
+    "get_default_registry",
+    "reset_default_registry",
+    "OllamaProvider",
+    "OpenAIProvider",
+    "GeminiProvider",
+    "AnthropicProvider",
+    "NullProvider",
+]
+
+

actshield/providers/anthropic_provider.py

@@ -0,0 +1,146 @@
+"""
+ActShield — Anthropic Provider
+===============================
+Security reasoning provider backed by Anthropic Claude models.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import time
+from typing import Any, Dict, Optional
+
+from actshield.providers.base import AnalysisResult, HealthReport, SecurityAIProvider
+
+logger = logging.getLogger("actshield.providers.anthropic")
+
+
+class AnthropicProvider(SecurityAIProvider):
+    """
+    Anthropic Claude Security Reasoning Provider.
+    Requires ANTHROPIC_API_KEY environment variable.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        model: str = "claude-3-5-sonnet-20241022",
+        timeout: float = 5.0,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("ANTHROPIC_API_KEY")
+        self.model = model or os.environ.get("ANTHROPIC_MODEL", "claude-3-5-sonnet-20241022")
+        self.timeout = timeout
+        self._client = None
+
+    @property
+    def provider_name(self) -> str:
+        return "anthropic"
+
+    @property
+    def model_name(self) -> str:
+        return self.model
+
+    @property
+    def is_available(self) -> bool:
+        return bool(self.api_key)
+
+    def _get_client(self):
+        if not self.is_available:
+            return None
+        if self._client is None:
+            try:
+                import anthropic
+                self._client = anthropic.Anthropic(api_key=self.api_key, timeout=self.timeout)
+            except ImportError:
+                logger.debug("anthropic python package not installed")
+                return None
+            except Exception as e:
+                logger.debug("Failed to init anthropic client: %s", e)
+                return None
+        return self._client
+
+    def analyze(self, packet: Dict[str, Any]) -> Optional[AnalysisResult]:
+        client = self._get_client()
+        if not client:
+            return None
+
+        t0 = time.monotonic()
+        system_prompt = (
+            "You are ActShield AI Security Reasoning Engine. Analyze the security packet.\n"
+            "Output ONLY a raw JSON object with keys: risk_score (0.0-1.0), threat_indicators (list of str), "
+            "recommendations (list of str), confidence (0.0-1.0)."
+        )
+        try:
+            response = client.messages.create(
+                model=self.model,
+                max_tokens=1024,
+                system=system_prompt,
+                messages=[
+                    {"role": "user", "content": json.dumps(packet, default=str)},
+                ],
+            )
+            latency = (time.monotonic() - t0) * 1000
+            content = response.content[0].text if response.content else "{}"
+            # Extract JSON block if wrapped in markdown
+            if "```json" in content:
+                content = content.split("```json")[1].split("```")[0].strip()
+            elif "```" in content:
+                content = content.split("```")[1].split("```")[0].strip()
+            
+            data = json.loads(content)
+            return AnalysisResult(
+                risk_score=float(data.get("risk_score", 0.0)),
+                threat_indicators=data.get("threat_indicators", []),
+                recommendations=data.get("recommendations", []),
+                provider_used=self.provider_name,
+                model_used=self.model_name,
+                latency_ms=latency,
+                raw_response=content,
+                confidence=float(data.get("confidence", 0.9)),
+            )
+        except Exception as exc:
+            logger.warning("Anthropic analysis failed: %s", exc)
+            return None
+
+    def health_check(self) -> HealthReport:
+        if not self.is_available:
+            return HealthReport(
+                available=False,
+                provider_name=self.provider_name,
+                model=self.model_name,
+                error="ANTHROPIC_API_KEY environment variable not set",
+            )
+        client = self._get_client()
+        if not client:
+            return HealthReport(
+                available=False,
+                provider_name=self.provider_name,
+                model=self.model_name,
+                error="anthropic library not installed or client init failed",
+            )
+        t0 = time.monotonic()
+        try:
+            # Low latency lightweight ping
+            client.messages.create(
+                model=self.model,
+                max_tokens=1,
+                messages=[{"role": "user", "content": "ping"}],
+            )
+            latency = (time.monotonic() - t0) * 1000
+            return HealthReport(
+                available=True,
+                provider_name=self.provider_name,
+                model=self.model_name,
+                latency_ms=latency,
+            )
+        except Exception as exc:
+            return HealthReport(
+                available=False,
+                provider_name=self.provider_name,
+                model=self.model_name,
+                latency_ms=(time.monotonic() - t0) * 1000,
+                error=str(exc),
+            )
+
+

actshield/providers/base.py

@@ -0,0 +1,160 @@
+"""
+ActShield Security AI Provider — Base Protocol
+================================================
+All AI intelligence providers must implement SecurityAIProvider.
+The deterministic enforcement path (PolicyEvaluator) never depends on this.
+If all providers fail, ActShield fails-safe to deterministic deny.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class AnalysisResult:
+    """Structured result from an AI security intelligence provider."""
+    risk_score: float                          # 0.0 – 1.0
+    threat_indicators: List[str] = field(default_factory=list)
+    recommendations: List[str] = field(default_factory=list)
+    provider_used: str = "unknown"
+    model_used: str = "unknown"
+    latency_ms: float = 0.0
+    raw_response: Optional[str] = None
+    analyzed_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    confidence: float = 1.0                    # 0.0 – 1.0
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def is_high_risk(self) -> bool:
+        return self.risk_score >= 0.7
+
+    @property
+    def is_critical(self) -> bool:
+        return self.risk_score >= 0.9
+
+
+@dataclass
+class HealthReport:
+    """Provider health status."""
+    available: bool
+    provider_name: str
+    model: str = "unknown"
+    latency_ms: float = 0.0
+    error: Optional[str] = None
+    checked_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def status_label(self) -> str:
+        return "AVAILABLE" if self.available else "UNAVAILABLE"
+
+
+class SecurityAIProvider(ABC):
+    """
+    Abstract base for all ActShield AI intelligence providers.
+
+    Implementations must NOT affect the deterministic enforcement boundary.
+    They provide advisory intelligence only — all block/allow decisions
+    are made by the PolicyEvaluator using deterministic rules.
+    """
+
+    @property
+    @abstractmethod
+    def provider_name(self) -> str:
+        """Human-readable provider name (e.g. 'ollama', 'openai', 'gemini')."""
+
+    @property
+    @abstractmethod
+    def model_name(self) -> str:
+        """Model identifier used by this provider."""
+
+    @property
+    def name(self) -> str:
+        """Alias for provider_name."""
+        return self.provider_name
+
+    @property
+    def provider_type(self) -> str:
+        """Provider taxonomy type (e.g. 'local_llm', 'cloud_llm', 'deterministic')."""
+        return getattr(self, "_provider_type", "llm")
+
+    def reason_sync(
+        self,
+        task_intent: str,
+        tool_name: str,
+        tool_params: Dict[str, Any],
+        agent_role: str = "agent",
+        caller_trust: str = "medium",
+    ) -> Any:
+        """Advisory reasoning helper."""
+        packet = {
+            "task_intent": task_intent,
+            "tool_name": tool_name,
+            "tool_params": tool_params,
+            "agent_role": agent_role,
+            "caller_trust": caller_trust,
+        }
+        res = self.analyze(packet)
+        from dataclasses import make_dataclass
+        SimpleReasoning = make_dataclass(
+            "SimpleReasoning",
+            [
+                ("threat_severity", str),
+                ("intent_alignment", str),
+                ("recommendation", str),
+                ("confidence", float),
+                ("explanation", str),
+            ]
+        )
+        if res:
+            sev = "HIGH" if res.is_high_risk else ("MEDIUM" if res.risk_score > 0.4 else "LOW")
+            rec = "BLOCK" if res.is_high_risk else "ALLOW"
+            return SimpleReasoning(
+                threat_severity=sev,
+                intent_alignment="ALIGNED" if not res.is_high_risk else "DEVIATED",
+                recommendation=rec,
+                confidence=res.confidence,
+                explanation="; ".join(res.threat_indicators) if res.threat_indicators else "Evaluated by AI provider",
+            )
+        return SimpleReasoning(
+            threat_severity="LOW",
+            intent_alignment="ALIGNED",
+            recommendation="ALLOW",
+            confidence=1.0,
+            explanation="Deterministic baseline policy authoritative",
+        )
+
+    @property
+    @abstractmethod
+    def is_available(self) -> bool:
+        """
+        Fast synchronous availability check (no network call).
+        Returns False if the provider is not configured or dependencies missing.
+        """
+
+    @abstractmethod
+    def analyze(self, packet: Dict[str, Any]) -> Optional[AnalysisResult]:
+        """
+        Run security intelligence analysis on a packet.
+
+        Args:
+            packet: A dict describing the security event/request context.
+
+        Returns:
+            AnalysisResult if successful, None if provider is unavailable or
+            fails. Callers MUST treat None as non-blocking (fail-safe).
+        """
+
+    @abstractmethod
+    def health_check(self) -> HealthReport:
+        """
+        Perform a full health check including a network/API call.
+        Must never raise — always return HealthReport(available=False) on error.
+        """
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__} provider={self.provider_name!r} model={self.model_name!r}>"
+