actshield 0.9.0__py3-none-any.whl

actshield/integrations/ai_secura_analysis.py

@@ -0,0 +1,236 @@
+"""Rich AI Secura Analysis output schema (Pydantic v2).
+
+This schema is the contract between the OllamaAISecuraAdapter and
+the rest of actshield.  The PolicyEvaluator reads structured fields
+from this object but remains the sole enforcement authority.
+"""
+
+from enum import Enum
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+import uuid
+
+
+class ThreatSeverity(str, Enum):
+    """Severity classification for a detected or suspected threat."""
+    LOW = "LOW"
+    MEDIUM = "MEDIUM"
+    HIGH = "HIGH"
+    CRITICAL = "CRITICAL"
+    UNKNOWN = "UNKNOWN"
+
+
+class IntentAlignment(str, Enum):
+    """Alignment of the requested action against the original user intent."""
+    ALIGNED = "ALIGNED"
+    POTENTIALLY_DRIFTING = "POTENTIALLY_DRIFTING"
+    VIOLATED = "VIOLATED"
+    UNKNOWN = "UNKNOWN"
+
+
+class AIRecommendation(str, Enum):
+    """Non-binding recommendation from AI Secura to the PolicyEvaluator."""
+    ALLOW = "ALLOW"
+    MONITOR = "MONITOR"
+    HUMAN_APPROVAL = "HUMAN_APPROVAL"
+    BLOCK = "BLOCK"
+    UNKNOWN = "UNKNOWN"
+
+
+class AttackTechnique(str, Enum):
+    """MITRE ATLAS / OWASP LLM Top-10 aligned attack technique labels."""
+    PROMPT_INJECTION = "prompt_injection"
+    INDIRECT_PROMPT_INJECTION = "indirect_prompt_injection"
+    JAILBREAK = "jailbreak"
+    SYSTEM_PROMPT_EXTRACTION = "system_prompt_extraction"
+    INSTRUCTION_HIJACKING = "instruction_hijacking"
+    SENSITIVE_INFORMATION_DISCLOSURE = "sensitive_information_disclosure"
+    DATA_EXFILTRATION = "data_exfiltration"
+    RAG_POISONING = "RAG_poisoning"
+    RAG_DATA_LEAKAGE = "RAG_data_leakage"
+    MALICIOUS_DOCUMENT = "malicious_document"
+    AGENT_HIJACKING = "agent_hijacking"
+    TOOL_ABUSE = "tool_abuse"
+    EXCESSIVE_AGENCY = "excessive_agency"
+    PRIVILEGE_ESCALATION = "privilege_escalation"
+    MCP_SECURITY = "MCP_security"
+    TOOL_POISONING = "tool_poisoning"
+    MALICIOUS_MCP_SERVER = "malicious_MCP_server"
+    AI_API_SECURITY = "AI_API_security"
+    AUTHENTICATION_FAILURE = "authentication_failure"
+    AUTHORIZATION_FAILURE = "authorization_failure"
+    AI_APPLICATION_VULNERABILITY = "AI_application_vulnerability"
+    ADVERSARIAL_ATTACK = "adversarial_attack"
+    CONTEXT_MANIPULATION = "context_manipulation"
+    AI_SUPPLY_CHAIN = "AI_supply_chain"
+    MODEL_DEPENDENCY_VULNERABILITY = "model_dependency_vulnerability"
+    AI_SECURITY_MONITORING = "AI_security_monitoring"
+    AI_SECURITY_EVALUATION = "AI_security_evaluation"
+    LLM_RELIABILITY_SECURITY = "LLM_reliability_security"
+    NONE = "none"
+    UNKNOWN = "unknown"
+
+
+class EvidenceTriad(BaseModel):
+    """Strict separation of observed facts, inferred conclusions, and unknowns.
+
+    AI Secura MUST NOT fabricate CVEs, CWE IDs, MITRE IDs, logs, or credentials.
+    If evidence is absent, the field belongs in 'unknown'.
+    """
+    observed: List[str] = Field(
+        default_factory=list,
+        description="Facts directly present in the ActShield evidence packet.",
+    )
+    inferred: List[str] = Field(
+        default_factory=list,
+        description="Reasonable conclusions derived from the observed evidence.",
+    )
+    unknown: List[str] = Field(
+        default_factory=list,
+        description="Aspects that cannot be established from the available evidence.",
+    )
+
+
+class AuthorityAnalysis(BaseModel):
+    """AI Secura reasoning about delegation authority — for explanation only, not enforcement."""
+    acting_agent: Optional[str] = None
+    delegated_capabilities: List[str] = Field(default_factory=list)
+    requested_capability: Optional[str] = None
+    required_capability: Optional[str] = None
+    delegation_chain: List[str] = Field(default_factory=list)
+    authority_violated: bool = False
+    reasoning: str = ""
+
+
+class TaintAnalysis(BaseModel):
+    """AI Secura reasoning about context taint lineage."""
+    context_id: Optional[str] = None
+    source: Optional[str] = None
+    trust_level: Optional[str] = None
+    taint_state: Optional[str] = None
+    origin_agent: Optional[str] = None
+    propagation_chain: List[str] = Field(default_factory=list)
+    is_tainted: bool = False
+    reasoning: str = ""
+
+
+class AISecuraAnalysis(BaseModel):
+    """Complete structured output from AI Secura reasoning engine.
+
+    IMPORTANT: This is *reasoning*, not enforcement.
+    The ActShield PolicyEvaluator is the sole enforcement authority.
+    ai_recommendation here is advisory only.
+    """
+    analysis_id: str = Field(default_factory=lambda: f"aisec35_{uuid.uuid4().hex[:12]}")
+
+    # --- Threat Classification ---
+    threat_type: str = Field(
+        default="unknown",
+        description="Primary threat type from the AI Secura security taxonomy.",
+    )
+    attack_category: str = Field(
+        default="unknown",
+        description="High-level attack category (e.g. 'injection', 'escalation', 'exfiltration').",
+    )
+    attack_technique: AttackTechnique = Field(
+        default=AttackTechnique.UNKNOWN,
+        description="Specific attack technique from the AI Secura taxonomy.",
+    )
+    severity: ThreatSeverity = Field(
+        default=ThreatSeverity.UNKNOWN,
+        description="Assessed threat severity.",
+    )
+    confidence: float = Field(
+        default=0.0,
+        ge=0.0,
+        le=1.0,
+        description="Confidence in the threat assessment (0.0 = uncertain, 1.0 = certain).",
+    )
+
+    # --- Evidence Model ---
+    evidence: EvidenceTriad = Field(default_factory=EvidenceTriad)
+    observed_indicators: List[str] = Field(
+        default_factory=list,
+        description="Specific observable indicators extracted from the security packet.",
+    )
+
+    # --- Alignment and Authority ---
+    intent_alignment: IntentAlignment = Field(
+        default=IntentAlignment.UNKNOWN,
+        description="Alignment of the requested action to original user intent.",
+    )
+    authority_analysis: AuthorityAnalysis = Field(default_factory=AuthorityAnalysis)
+    taint_analysis: TaintAnalysis = Field(default_factory=TaintAnalysis)
+
+    # --- MITRE References (only when directly supported by evidence) ---
+    mitre_attack_id: Optional[str] = Field(
+        default=None,
+        description="MITRE ATT&CK ID — only set when directly supported by observed evidence.",
+    )
+    mitre_atlas_id: Optional[str] = Field(
+        default=None,
+        description="MITRE ATLAS ID — only set when directly supported by observed evidence.",
+    )
+
+    # --- Analysis Narrative ---
+    analysis: str = Field(
+        default="",
+        description="Comprehensive reasoning narrative from AI Secura.",
+    )
+    impact: str = Field(
+        default="",
+        description="Potential impact if the threat is not mitigated.",
+    )
+    influencing_context: str = Field(
+        default="",
+        description="Which context data items most influenced this analysis.",
+    )
+
+    # --- Remediation ---
+    recommended_actions: List[str] = Field(
+        default_factory=list,
+        description="Security recommendations (advisory only).",
+    )
+    containment: List[str] = Field(
+        default_factory=list,
+        description="Immediate containment steps.",
+    )
+    remediation: List[str] = Field(
+        default_factory=list,
+        description="Longer-term remediation measures.",
+    )
+    additional_information_required: List[str] = Field(
+        default_factory=list,
+        description="Additional context or evidence needed for a definitive assessment.",
+    )
+
+    # --- Advisory Recommendation ---
+    ai_recommendation: AIRecommendation = Field(
+        default=AIRecommendation.UNKNOWN,
+        description=(
+            "NON-BINDING advisory recommendation to PolicyEvaluator. "
+            "PolicyEvaluator may override this at any time."
+        ),
+    )
+
+    # --- Provider Metadata ---
+    provider: str = Field(default="local", description="Provider: 'ollama' or 'local'.")
+    model: str = Field(default="local-heuristic")
+    latency_ms: float = Field(default=0.0, description="Analysis latency in milliseconds.")
+    ai_unavailable: bool = Field(
+        default=False,
+        description=(
+            "True when Ollama is unreachable, timed out, or returned irrecoverably malformed output. "
+            "When True, ActShield deterministic policy continues as sole enforcer."
+        ),
+    )
+    json_repaired: bool = Field(
+        default=False,
+        description="True if the model output required one JSON repair attempt.",
+    )
+    raw_response: Optional[str] = Field(
+        default=None,
+        description="Raw model response string (for debugging). Redacted in production events.",
+    )
+
+

actshield/integrations/apiris.py

@@ -0,0 +1,122 @@
+"""APIRIS API decision-intelligence and tool security interface."""
+
+from typing import Any, Callable, Dict, List, Optional, Protocol, runtime_checkable
+import uuid
+from pydantic import BaseModel, Field
+
+from actshield.risk.models import RiskLevel, RiskSignal
+from actshield.tools.tool import ToolRequest
+
+
+class APIAnalysis(BaseModel):
+    """API & tool intelligence analysis returned by APIRIS."""
+    analysis_id: str
+    tool_id: str
+    tool_name: str
+    risk_score: float = Field(default=0.0, ge=0.0, le=1.0)
+    anomaly_score: float = Field(default=0.0, ge=0.0, le=1.0)
+    cve_indicators: List[str] = Field(default_factory=list)
+    vendor_reputation: str = "TRUSTED"
+    latency_ms_estimate: float = 50.0
+    cost_estimate_usd: float = 0.0
+    recommended_action: str = "ALLOW"
+    signals: List[RiskSignal] = Field(default_factory=list)
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+@runtime_checkable
+class APIIntelligence(Protocol):
+    """Protocol for APIRIS API intelligence engine."""
+
+    def analyze(self, request: ToolRequest) -> APIAnalysis:
+        """Analyze tool request metadata, endpoint parameters, and reputation."""
+        ...
+
+
+class APIRISClient(APIIntelligence):
+    """APIRIS API decision intelligence client.
+    
+    Inspects endpoint reputation, argument injection signatures, rate anomalies,
+    and returns recommendations (ALLOW, MONITOR, HUMAN_APPROVAL, BLOCK).
+    """
+
+    def __init__(
+        self,
+        api_endpoint: Optional[str] = None,
+        api_key: Optional[str] = None,
+        custom_engine: Optional[Callable[[ToolRequest], APIAnalysis]] = None,
+    ) -> None:
+        self.api_endpoint = api_endpoint or "https://apiris.internal/v1/analyze"
+        self.api_key = api_key or "apiris-live-token"
+        self.custom_engine = custom_engine
+
+    def analyze(self, request: ToolRequest) -> APIAnalysis:
+        """Perform APIRIS decision intelligence analysis on the requested tool invocation."""
+        if self.custom_engine:
+            return self.custom_engine(request)
+
+        analysis_id = f"apiris_{uuid.uuid4().hex[:12]}"
+        signals: List[RiskSignal] = []
+        cves: List[str] = []
+        risk_score = 0.05
+        anomaly_score = 0.02
+        rec_action = "ALLOW"
+
+        args_str = str(request.arguments).lower()
+        tool_name_lower = (request.tool_name or "").lower()
+
+        # 1. Command injection pattern checks
+        if any(pat in args_str for pat in ("rm -rf", "drop table", "--exec", "cmd.exe", "eval(", "; cat /etc/passwd", "bash -i")):
+            risk_score = 0.95
+            anomaly_score = 0.98
+            rec_action = "BLOCK"
+            signals.append(
+                RiskSignal(
+                    source="apiris",
+                    risk_level=RiskLevel.CRITICAL,
+                    score=0.95,
+                    indicator="APIRIS_COMMAND_INJECTION_PATTERN",
+                    details={"arguments": request.arguments},
+                )
+            )
+
+        # 2. SSRF / Untrusted domain check
+        if any(pat in args_str for pat in ("169.254.169.254", "localhost:8080", "127.0.0.1", "evil-exfil.com")):
+            risk_score = 0.90
+            rec_action = "BLOCK"
+            signals.append(
+                RiskSignal(
+                    source="apiris",
+                    risk_level=RiskLevel.CRITICAL,
+                    score=0.90,
+                    indicator="APIRIS_SSRF_OR_UNTRUSTED_DESTINATION",
+                    details={"arguments": request.arguments},
+                )
+            )
+
+        # 3. High sensitivity / Financial tool heuristic
+        if "customer_db" in tool_name_lower or "pii" in tool_name_lower:
+            risk_score = max(risk_score, 0.40)
+            vendor_rep = "INTERNAL_RESTRICTED"
+        else:
+            vendor_rep = "TRUSTED"
+
+        return APIAnalysis(
+            analysis_id=analysis_id,
+            tool_id=request.tool_id,
+            tool_name=request.tool_name,
+            risk_score=risk_score,
+            anomaly_score=anomaly_score,
+            cve_indicators=cves,
+            vendor_reputation=vendor_rep,
+            latency_ms_estimate=45.0,
+            recommended_action=rec_action,
+            signals=signals,
+            metadata={"evaluated_by": "APIRIS-v3.0"},
+        )
+
+
+class LocalAPIRISAdapter(APIRISClient):
+    """Backward-compatible alias for local execution."""
+    pass
+

actshield/integrations/few_shot.py

@@ -0,0 +1,104 @@
+"""Deterministic few-shot example selector for AI Secura prompts.
+
+Selects up to MAX_EXAMPLES relevant examples based on:
+  - Protocol (mcp, http, rag, tool, api)
+  - Taint state (TAINTED, CLEAN)
+  - Resource sensitivity (CRITICAL, HIGH, MEDIUM, LOW)
+  - Attack category hint
+
+No vector database. Pure rule-based selection from the examples directory.
+"""
+
+import json
+import pathlib
+from typing import Any, Dict, List, Optional
+
+_EXAMPLES_DIR = pathlib.Path(__file__).parent / "prompts" / "examples"
+MAX_EXAMPLES = 4
+
+
+def _load_example(path: pathlib.Path) -> Optional[Dict[str, Any]]:
+    try:
+        with open(path, encoding="utf-8") as f:
+            return json.load(f)
+    except Exception:
+        return None
+
+
+def _score_example(ex: Dict[str, Any], context: Dict[str, Any]) -> int:
+    """Return relevance score (higher = more relevant)."""
+    score = 0
+    ex_tags = set(ex.get("tags", []))
+
+    # Protocol match
+    provenance = context.get("context_provenance", [])
+    src = " ".join(str(p) for p in provenance).lower()
+    tool_name = str(context.get("tool", {}).get("name", "")).lower()
+    if "mcp" in src and "mcp" in ex_tags:
+        score += 3
+    if "http" in src or "api" in src:
+        if "http" in ex_tags or "api" in ex_tags:
+            score += 3
+    if "rag" in src and "rag" in ex_tags:
+        score += 3
+
+    # Taint state match
+    taint_states = context.get("taint_states", [])
+    has_taint = any(t in ("TAINTED", "UNTRUSTED") for t in taint_states)
+    if has_taint and "tainted" in ex_tags:
+        score += 2
+    if not has_taint and "clean" in ex_tags:
+        score += 2
+
+    # Sensitivity match
+    sensitivity = str(context.get("resource", {}).get("sensitivity", "")).upper()
+    if sensitivity in ("CRITICAL", "HIGH") and "critical_sink" in ex_tags:
+        score += 2
+    if sensitivity in ("LOW", "MEDIUM") and "low_risk" in ex_tags:
+        score += 1
+
+    # Attack category match
+    ex_threat = ex.get("expected_output", {}).get("attack_technique", "")
+    det_policy = context.get("deterministic_policy", {})
+    reason_codes = " ".join(det_policy.get("reason_codes", []))
+    if "injection" in reason_codes.lower() and "injection" in ex_threat:
+        score += 2
+    if "authority" in reason_codes.lower() and "escalation" in ex_threat:
+        score += 2
+
+    return score
+
+
+def select_few_shot_examples(context: Dict[str, Any]) -> List[Dict[str, Any]]:
+    """Return up to MAX_EXAMPLES ordered by relevance to context."""
+    if not _EXAMPLES_DIR.exists():
+        return []
+
+    examples = []
+    for path in sorted(_EXAMPLES_DIR.glob("*.json")):
+        ex = _load_example(path)
+        if ex:
+            ex["_score"] = _score_example(ex, context)
+            examples.append(ex)
+
+    examples.sort(key=lambda e: e["_score"], reverse=True)
+    return [
+        {k: v for k, v in ex.items() if k != "_score"}
+        for ex in examples[:MAX_EXAMPLES]
+    ]
+
+
+def format_examples_for_prompt(examples: List[Dict[str, Any]]) -> str:
+    """Format selected examples as a few-shot block for the system prompt."""
+    if not examples:
+        return ""
+    lines = ["\n\n### FEW-SHOT EXAMPLES\n"]
+    for i, ex in enumerate(examples, 1):
+        lines.append(f"#### Example {i}: {ex.get('description', '')}\n")
+        lines.append("Input:\n```json")
+        lines.append(json.dumps(ex.get("input", {}), indent=2))
+        lines.append("```\n")
+        lines.append("Expected Output:\n```json")
+        lines.append(json.dumps(ex.get("expected_output", {}), indent=2))
+        lines.append("```\n")
+    return "\n".join(lines)