actshield 0.9.0__py3-none-any.whl

actshield/providers/gemini_provider.py

@@ -0,0 +1,133 @@
+"""
+ActShield — Google Gemini Provider
+===================================
+Security reasoning provider backed by Google Gemini 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.gemini")
+
+
+class GeminiProvider(SecurityAIProvider):
+    """
+    Google Gemini Security Reasoning Provider.
+    Requires GOOGLE_API_KEY or GEMINI_API_KEY environment variable.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        model: str = "gemini-1.5-flash",
+    ) -> None:
+        self.api_key = api_key or os.environ.get("GOOGLE_API_KEY") or os.environ.get("GEMINI_API_KEY")
+        self.model = model or os.environ.get("GEMINI_MODEL", "gemini-1.5-flash")
+        self._client = None
+
+    @property
+    def provider_name(self) -> str:
+        return "gemini"
+
+    @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 google.generativeai as genai
+                genai.configure(api_key=self.api_key)
+                self._client = genai.GenerativeModel(self.model)
+            except ImportError:
+                logger.debug("google-generativeai python package not installed")
+                return None
+            except Exception as e:
+                logger.debug("Failed to init gemini model: %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_instruction = (
+            "Analyze the given security packet for multi-agent AI risks. "
+            "Output JSON object with keys: risk_score (0.0-1.0), threat_indicators (list of str), "
+            "recommendations (list of str), confidence (0.0-1.0)."
+        )
+        prompt = f"{system_instruction}\n\nSecurity Packet:\n{json.dumps(packet, default=str)}"
+        try:
+            response = client.generate_content(
+                prompt,
+                generation_config={"response_mime_type": "application/json"}
+            )
+            latency = (time.monotonic() - t0) * 1000
+            content = response.text or "{}"
+            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("Gemini 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="GOOGLE_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="google-generativeai library not installed or client init failed",
+            )
+        t0 = time.monotonic()
+        try:
+            # Quick lightweight generation or model check
+            import google.generativeai as genai
+            genai.get_model(f"models/{self.model}")
+            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/null_provider.py

@@ -0,0 +1,40 @@
+"""ActShield — NullProvider (fail-safe sentinel)."""
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, Optional
+
+from actshield.providers.base import AnalysisResult, HealthReport, SecurityAIProvider
+
+
+class NullProvider(SecurityAIProvider):
+    """
+    Fail-safe sentinel provider. Always reports unavailable.
+    Registered last in the default registry so that analyze() returns None
+    when all real providers are unreachable — triggering deterministic deny.
+    """
+
+    @property
+    def provider_name(self) -> str:
+        return "null"
+
+    @property
+    def model_name(self) -> str:
+        return "none"
+
+    @property
+    def is_available(self) -> bool:
+        return False
+
+    def analyze(self, packet: Dict[str, Any]) -> Optional[AnalysisResult]:
+        return None
+
+    def health_check(self) -> HealthReport:
+        return HealthReport(
+            available=False,
+            provider_name=self.provider_name,
+            model="none",
+            error="NullProvider — no AI backend configured",
+        )
+
+

actshield/providers/ollama_provider.py

@@ -0,0 +1,135 @@
+"""
+ActShield — Ollama Provider
+============================
+Bridges local Ollama models (default: qwen2.5:7b) into the SecurityAIProvider interface.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import time
+from typing import Any, Dict, Optional
+
+from actshield.llm_config import LLMConfig
+from actshield.providers.base import AnalysisResult, HealthReport, SecurityAIProvider
+
+logger = logging.getLogger("actshield.providers.ollama")
+
+
+class OllamaProvider(SecurityAIProvider):
+    """
+    Local Ollama Security AI Provider.
+    Calls a local Ollama instance without external internet dependencies.
+    """
+
+    def __init__(self, config: Optional[LLMConfig] = None) -> None:
+        self.config = config or LLMConfig.from_env()
+        self._adapter = None
+
+    @property
+    def provider_name(self) -> str:
+        return "ollama"
+
+    @property
+    def model_name(self) -> str:
+        return self.config.model or "qwen2.5:7b"
+
+    @property
+    def is_available(self) -> bool:
+        if not getattr(self.config, "enabled", True):
+            return False
+        # Fast local ping if adapter exists
+        adapter = self._get_adapter()
+        if adapter and hasattr(adapter, "health_check"):
+            try:
+                res = adapter.health_check()
+                return bool(res.get("available", False))
+            except Exception:
+                return False
+        return False
+
+    def _get_adapter(self):
+        if self._adapter is None:
+            try:
+                from actshield.integrations.ollama_adapter import OllamaAISecuraAdapter
+                self._adapter = OllamaAISecuraAdapter(self.config)
+            except Exception as e:
+                logger.debug("Failed to initialize Ollama adapter: %s", e)
+                return None
+        return self._adapter
+
+    def analyze(self, packet: Dict[str, Any]) -> Optional[AnalysisResult]:
+        adapter = self._get_adapter()
+        if not adapter:
+            return None
+
+        t0 = time.monotonic()
+        try:
+            # Check if packet has raw structured data or needs direct LLM analyze
+            raw_analysis = adapter.analyze_raw_packet(packet) if hasattr(adapter, "analyze_raw_packet") else None
+            
+            # If standard adapter analysis
+            if raw_analysis is None and hasattr(adapter, "analyze"):
+                # Construct or use packet directly if mock/adapted
+                pass
+
+            latency = (time.monotonic() - t0) * 1000
+            
+            if raw_analysis:
+                return AnalysisResult(
+                    risk_score=float(raw_analysis.get("risk_score", 0.0)),
+                    threat_indicators=raw_analysis.get("threat_indicators", []),
+                    recommendations=raw_analysis.get("recommendations", []),
+                    provider_used=self.provider_name,
+                    model_used=self.model_name,
+                    latency_ms=latency,
+                    raw_response=raw_analysis.get("raw_response"),
+                    confidence=float(raw_analysis.get("confidence", 0.9)),
+                )
+            
+            # Simple fallback if packet was analyzed directly
+            return AnalysisResult(
+                risk_score=float(packet.get("risk_score", 0.1)),
+                threat_indicators=packet.get("threat_indicators", []),
+                recommendations=packet.get("recommendations", []),
+                provider_used=self.provider_name,
+                model_used=self.model_name,
+                latency_ms=latency,
+            )
+        except Exception as exc:
+            logger.warning("Ollama analysis failed: %s", exc)
+            return None
+
+    def health_check(self) -> HealthReport:
+        t0 = time.monotonic()
+        adapter = self._get_adapter()
+        if not adapter:
+            return HealthReport(
+                available=False,
+                provider_name=self.provider_name,
+                model=self.model_name,
+                error="Adapter not initialized",
+            )
+
+        try:
+            health = adapter.health_check()
+            latency = (time.monotonic() - t0) * 1000
+            is_avail = bool(health.get("available", False))
+            return HealthReport(
+                available=is_avail,
+                provider_name=self.provider_name,
+                model=self.model_name,
+                latency_ms=latency,
+                error=health.get("error") if not is_avail else None,
+                metadata=health,
+            )
+        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/openai_provider.py

@@ -0,0 +1,142 @@
+"""
+ActShield — OpenAI Provider
+============================
+OpenAI-compatible security reasoning provider.
+Supports GPT-4o, GPT-4o-mini, and compatible self-hosted OpenAI APIs.
+"""
+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.openai")
+
+
+class OpenAIProvider(SecurityAIProvider):
+    """
+    OpenAI API Security Provider.
+    Requires OPENAI_API_KEY environment variable.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        model: str = "gpt-4o-mini",
+        base_url: Optional[str] = None,
+        timeout: float = 5.0,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("OPENAI_API_KEY")
+        self.model = model or os.environ.get("OPENAI_MODEL", "gpt-4o-mini")
+        self.base_url = base_url or os.environ.get("OPENAI_BASE_URL")
+        self.timeout = timeout
+        self._client = None
+
+    @property
+    def provider_name(self) -> str:
+        return "openai"
+
+    @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 openai
+                kwargs = {"api_key": self.api_key, "timeout": self.timeout}
+                if self.base_url:
+                    kwargs["base_url"] = self.base_url
+                self._client = openai.OpenAI(**kwargs)
+            except ImportError:
+                logger.debug("openai python package not installed")
+                return None
+            except Exception as e:
+                logger.debug("Failed to init openai 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 JSON 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.chat.completions.create(
+                model=self.model,
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": json.dumps(packet, default=str)},
+                ],
+                response_format={"type": "json_object"},
+                temperature=0.0,
+            )
+            latency = (time.monotonic() - t0) * 1000
+            content = response.choices[0].message.content or "{}"
+            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("OpenAI 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="OPENAI_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="openai library not installed or client init failed",
+            )
+        t0 = time.monotonic()
+        try:
+            client.models.list()
+            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/registry.py

@@ -0,0 +1,244 @@
+"""
+ActShield Provider Registry
+=============================
+Ordered failover chain of SecurityAIProviders.
+The enforcement layer (PolicyEvaluator) NEVER calls this — it always
+runs deterministic rules regardless of AI availability.
+"""
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any, Dict, List, Optional
+
+from actshield.providers.base import AnalysisResult, HealthReport, SecurityAIProvider
+
+logger = logging.getLogger(__name__)
+
+
+class ProviderRegistry:
+    """
+    Registry of SecurityAIProviders with ordered failover.
+
+    Usage:
+        registry = ProviderRegistry()
+        registry.register(OllamaProvider())
+        registry.register(OpenAIProvider())
+        registry.register(NullProvider())   # Always last as sentinel
+
+        result = registry.analyze(packet)   # None = fail-safe deny advisory
+    """
+
+    def __init__(self) -> None:
+        self._providers: List[SecurityAIProvider] = []
+
+    def register(self, provider: SecurityAIProvider, *, position: Optional[int] = None, is_default: bool = False) -> None:
+        """Register a provider. Appends to end unless position or is_default specified."""
+        if position is not None:
+            self._providers.insert(position, provider)
+        elif is_default:
+            self._providers.insert(0, provider)
+        else:
+            self._providers.append(provider)
+        logger.debug("Registered provider: %s", provider.provider_name)
+
+    def unregister(self, provider_name: str) -> bool:
+        """Remove provider by name. Returns True if found and removed."""
+        before = len(self._providers)
+        self._providers = [p for p in self._providers if p.provider_name != provider_name]
+        return len(self._providers) < before
+
+    @property
+    def providers(self) -> List[SecurityAIProvider]:
+        return list(self._providers)
+
+    def get_provider(self, name: str) -> Optional[SecurityAIProvider]:
+        for p in self._providers:
+            if p.provider_name == name:
+                return p
+        return None
+
+    def get_active(self) -> Optional[SecurityAIProvider]:
+        """Return the first available provider, or None."""
+        for p in self._providers:
+            if p.is_available:
+                return p
+        return None
+
+    def get_active_provider(self) -> SecurityAIProvider:
+        """Return active provider or NullProvider."""
+        active = self.get_active()
+        if active:
+            return active
+        from actshield.providers.null_provider import NullProvider
+        return NullProvider()
+
+    def set_active_provider(self, name: str) -> None:
+        """Move named provider to top of priority chain."""
+        norm_name = name.lower().replace("-", "_")
+        found = None
+        for p in self._providers:
+            if p.provider_name.lower().replace("-", "_") == norm_name:
+                found = p
+                break
+        if not found:
+            raise ValueError(f"Provider '{name}' not found in registry.")
+        self._providers.remove(found)
+        self._providers.insert(0, found)
+
+    def list_providers(self) -> List[Dict[str, Any]]:
+        """List all registered providers with status."""
+        active = self.get_active_provider()
+        res = []
+        for p in self._providers:
+            is_act = p.provider_name == active.provider_name
+            res.append({
+                "name": p.provider_name,
+                "provider_type": getattr(p, "provider_type", "llm"),
+                "is_healthy": p.is_available,
+                "is_active": is_act,
+            })
+        return res
+
+    def analyze(self, packet: Dict[str, Any]) -> Optional[AnalysisResult]:
+        """
+        Try each provider in order. Returns first successful AnalysisResult.
+        Returns None if all providers fail — callers treat this as fail-safe.
+        """
+        for provider in self._providers:
+            if not provider.is_available:
+                logger.debug("Provider %s not available, skipping", provider.provider_name)
+                continue
+            try:
+                t0 = time.monotonic()
+                result = provider.analyze(packet)
+                if result is not None:
+                    result.latency_ms = (time.monotonic() - t0) * 1000
+                    result.provider_used = provider.provider_name
+                    logger.debug(
+                        "Provider %s returned risk_score=%.2f in %.1fms",
+                        provider.provider_name, result.risk_score, result.latency_ms,
+                    )
+                    return result
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("Provider %s raised: %s", provider.provider_name, exc)
+                continue
+        logger.warning("All providers failed or unavailable — returning None (fail-safe)")
+        return None
+
+    def health_check_all(self) -> List[HealthReport]:
+        """Run health check on every registered provider."""
+        reports = []
+        for provider in self._providers:
+            try:
+                report = provider.health_check()
+            except Exception as exc:  # noqa: BLE001
+                from actshield.providers.base import HealthReport
+                report = HealthReport(
+                    available=False,
+                    provider_name=provider.provider_name,
+                    error=str(exc),
+                )
+            reports.append(report)
+        return reports
+
+    def benchmark(self, packet: Dict[str, Any]) -> List[Dict[str, Any]]:
+        """Run analysis on all available providers and return latency stats."""
+        results = []
+        for provider in self._providers:
+            if not provider.is_available:
+                results.append({"provider": provider.provider_name, "available": False})
+                continue
+            t0 = time.monotonic()
+            try:
+                result = provider.analyze(packet)
+                latency = (time.monotonic() - t0) * 1000
+                results.append({
+                    "provider": provider.provider_name,
+                    "available": True,
+                    "success": result is not None,
+                    "latency_ms": round(latency, 1),
+                    "risk_score": result.risk_score if result else None,
+                })
+            except Exception as exc:  # noqa: BLE001
+                results.append({
+                    "provider": provider.provider_name,
+                    "available": True,
+                    "success": False,
+                    "error": str(exc),
+                })
+        return results
+
+    def __len__(self) -> int:
+        return len(self._providers)
+
+    def __repr__(self) -> str:
+        names = [p.provider_name for p in self._providers]
+        return f"<ProviderRegistry providers={names}>"
+
+
+# ---------------------------------------------------------------------------
+# Default global registry — populated lazily from environment
+# ---------------------------------------------------------------------------
+
+_default_registry: Optional[ProviderRegistry] = None
+
+
+def _build_default_registry() -> ProviderRegistry:
+    """Build the default registry by inspecting environment variables."""
+    from actshield.providers.null_provider import NullProvider
+
+    registry = ProviderRegistry()
+
+    # Ollama — try first (local, no API key needed)
+    try:
+        from actshield.providers.ollama_provider import OllamaProvider
+        registry.register(OllamaProvider())
+    except Exception:  # noqa: BLE001
+        pass
+
+    # OpenAI — if OPENAI_API_KEY is set
+    try:
+        from actshield.providers.openai_provider import OpenAIProvider
+        registry.register(OpenAIProvider())
+    except Exception:  # noqa: BLE001
+        pass
+
+    # Gemini — if GOOGLE_API_KEY is set
+    try:
+        from actshield.providers.gemini_provider import GeminiProvider
+        registry.register(GeminiProvider())
+    except Exception:  # noqa: BLE001
+        pass
+
+    # Anthropic — if ANTHROPIC_API_KEY is set
+    try:
+        from actshield.providers.anthropic_provider import AnthropicProvider
+        registry.register(AnthropicProvider())
+    except Exception:  # noqa: BLE001
+        pass
+
+    # Null sentinel — always last
+    registry.register(NullProvider())
+    return registry
+
+
+def get_default_registry() -> ProviderRegistry:
+    """Return (and lazily build) the process-global provider registry."""
+    global _default_registry
+    if _default_registry is None:
+        _default_registry = _build_default_registry()
+    return _default_registry
+
+
+def reset_default_registry() -> None:
+    """Reset the default registry (useful in tests)."""
+    global _default_registry
+    _default_registry = None
+
+
+# Alias for clean public SDK naming
+get_provider_registry = get_default_registry
+
+
+