actshield 0.9.0__py3-none-any.whl

actshield/llm_config.py

@@ -0,0 +1,89 @@
+"""LLM provider configuration for ActShield AI Secura reasoning engine.
+
+Reads from environment variables. No hardcoded values.
+
+Variables:
+    AGENTGUARD_LLM_PROVIDER   : 'ollama' or 'local' (default: 'local')
+    AGENTGUARD_LLM_MODEL      : model name (default: 'qwen2.5:7b')
+    AGENTGUARD_OLLAMA_BASE_URL: Ollama server URL (default: 'http://localhost:11434')
+    AGENTGUARD_LLM_TIMEOUT    : request timeout seconds (default: 30)
+    AGENTGUARD_LLM_MAX_TOKENS : max response tokens (default: 2048)
+    AGENTGUARD_LLM_TEMPERATURE: sampling temperature (default: 0.1)
+"""
+
+import os
+from typing import Literal
+from pydantic import BaseModel, Field
+
+
+class LLMConfig(BaseModel):
+    """Runtime configuration for the AI Secura LLM reasoning engine."""
+
+    provider: Literal["ollama", "local"] = Field(
+        default="local",
+        description="LLM provider: 'ollama' for real AI reasoning, 'local' for deterministic heuristic adapter",
+    )
+    model: str = Field(
+        default="qwen2.5:7b",
+        description="Model identifier (e.g. 'qwen2.5:7b', 'ai-secura')",
+    )
+    ollama_base_url: str = Field(
+        default="http://localhost:11434",
+        description="Base URL for the Ollama server",
+    )
+    timeout_seconds: int = Field(
+        default=60,
+        ge=5,
+        le=300,
+        description="HTTP request timeout in seconds for Ollama calls",
+    )
+    max_tokens: int = Field(
+        default=512,
+        ge=256,
+        le=8192,
+        description="Maximum tokens the model may generate per analysis",
+    )
+    temperature: float = Field(
+        default=0.1,
+        ge=0.0,
+        le=1.0,
+        description="Sampling temperature. Low values produce deterministic, consistent security analysis.",
+    )
+    num_ctx: int = Field(
+        default=8192,
+        ge=2048,
+        description="Ollama context window size in tokens",
+    )
+    repair_on_invalid_json: bool = Field(
+        default=True,
+        description="Attempt exactly one JSON repair request if the initial response is malformed",
+    )
+    fallback_to_local_on_error: bool = Field(
+        default=True,
+        description="Return an ai_unavailable=True analysis when Ollama is unreachable",
+    )
+
+    @classmethod
+    def from_env(cls) -> "LLMConfig":
+        return cls(
+            provider=os.environ.get("AGENTGUARD_LLM_PROVIDER", "local"),  # type: ignore[arg-type]
+            model=os.environ.get("AGENTGUARD_LLM_MODEL", "qwen2.5:7b"),
+            ollama_base_url=os.environ.get("AGENTGUARD_OLLAMA_BASE_URL", "http://localhost:11434"),
+            timeout_seconds=int(os.environ.get("AGENTGUARD_LLM_TIMEOUT", "30")),
+            max_tokens=int(os.environ.get("AGENTGUARD_LLM_MAX_TOKENS", "2048")),
+            temperature=float(os.environ.get("AGENTGUARD_LLM_TEMPERATURE", "0.1")),
+            num_ctx=int(os.environ.get("AGENTGUARD_LLM_NUM_CTX", "8192")),
+        )
+
+    @property
+    def ollama_generate_url(self) -> str:
+        return f"{self.ollama_base_url.rstrip('/')}/api/generate"
+
+    @property
+    def ollama_tags_url(self) -> str:
+        return f"{self.ollama_base_url.rstrip('/')}/api/tags"
+
+    @property
+    def is_ollama(self) -> bool:
+        return self.provider == "ollama"
+

actshield/offensive/__init__.py

@@ -0,0 +1,95 @@
+"""ActShield Offensive Security Validation Engine."""
+
+from actshield.offensive.attack import (
+    AttackCase,
+    AttackType,
+    ExpectedBehavior,
+    SafetyClass,
+)
+from actshield.offensive.target import (
+    AttackTarget,
+    TargetEnvironment,
+    TargetRegistry,
+    target_registry,
+)
+from actshield.offensive.safety import (
+    SafetyValidationResult,
+    SafetyValidator,
+    safety_validator,
+)
+from actshield.offensive.evidence import SecurityAnalysisEvidence
+from actshield.offensive.results import (
+    AttackStatus,
+    ExecutionEvidence,
+    OffensiveAttackResult,
+)
+from actshield.offensive.evaluator import AttackEvaluator
+from actshield.offensive.mutation import (
+    MutationEngine,
+    MutationStrategy,
+)
+from actshield.offensive.campaign import (
+    AttackCampaign,
+    CampaignSummary,
+)
+from actshield.offensive.corpus import (
+    AttackCorpus,
+    attack_corpus,
+)
+from actshield.offensive.generator import (
+    AIAttackGenerator,
+    OFFENSIVE_SYSTEM_PROMPT,
+)
+from actshield.offensive.vulnerable_target import VulnerableDemoTarget
+from actshield.offensive.engine import OffensiveEngine
+from actshield.offensive.adaptive import (
+    AdaptiveAttackSelector,
+    AdaptiveEngine,
+    BoundarySearchEngine,
+    CampaignMemory,
+    DefenseCategory,
+    DefenseFeedback,
+    FeedbackAnalyzer,
+    MutationNode,
+    MutationPlanner,
+)
+
+__all__ = [
+    "AttackCase",
+    "AttackType",
+    "ExpectedBehavior",
+    "SafetyClass",
+    "AttackTarget",
+    "TargetEnvironment",
+    "TargetRegistry",
+    "target_registry",
+    "SafetyValidationResult",
+    "SafetyValidator",
+    "safety_validator",
+    "SecurityAnalysisEvidence",
+    "AttackStatus",
+    "ExecutionEvidence",
+    "OffensiveAttackResult",
+    "AttackEvaluator",
+    "MutationEngine",
+    "MutationStrategy",
+    "AttackCampaign",
+    "CampaignSummary",
+    "AttackCorpus",
+    "attack_corpus",
+    "AIAttackGenerator",
+    "OFFENSIVE_SYSTEM_PROMPT",
+    "VulnerableDemoTarget",
+    "OffensiveEngine",
+    "AdaptiveAttackSelector",
+    "AdaptiveEngine",
+    "BoundarySearchEngine",
+    "CampaignMemory",
+    "DefenseCategory",
+    "DefenseFeedback",
+    "FeedbackAnalyzer",
+    "MutationNode",
+    "MutationPlanner",
+]
+
+

actshield/offensive/adaptive/__init__.py

@@ -0,0 +1,22 @@
+"""ActShield Adaptive Offensive Validation Subsystem."""
+
+from actshield.offensive.adaptive.campaign_memory import CampaignMemory, MutationNode
+from actshield.offensive.adaptive.feedback import DefenseCategory, DefenseFeedback, FeedbackAnalyzer
+from actshield.offensive.adaptive.mutation_planner import MutationPlanner
+from actshield.offensive.adaptive.attack_selector import AdaptiveAttackSelector
+from actshield.offensive.adaptive.boundary_search import BoundarySearchEngine
+from actshield.offensive.adaptive.adaptive_engine import AdaptiveEngine
+
+__all__ = [
+    "CampaignMemory",
+    "MutationNode",
+    "DefenseCategory",
+    "DefenseFeedback",
+    "FeedbackAnalyzer",
+    "MutationPlanner",
+    "AdaptiveAttackSelector",
+    "BoundarySearchEngine",
+    "AdaptiveEngine",
+]
+
+

actshield/offensive/adaptive/adaptive_engine.py

@@ -0,0 +1,165 @@
+"""Adaptive Offensive Engine — Master orchestrator for adaptive validation campaigns."""
+
+import json
+import logging
+import os
+import pathlib
+import time
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Tuple
+
+from actshield.offensive.attack import AttackCase, AttackType
+from actshield.offensive.campaign import AttackCampaign, CampaignSummary
+from actshield.offensive.corpus import AttackCorpus, attack_corpus
+from actshield.offensive.engine import OffensiveEngine
+from actshield.offensive.results import AttackStatus, OffensiveAttackResult
+from actshield.offensive.safety import SafetyValidator, safety_validator
+from actshield.offensive.target import AttackTarget, TargetRegistry, target_registry
+from actshield.offensive.adaptive.attack_selector import AdaptiveAttackSelector
+from actshield.offensive.adaptive.boundary_search import BoundarySearchEngine
+from actshield.offensive.adaptive.campaign_memory import CampaignMemory, MutationNode
+
+logger = logging.getLogger("actshield.offensive.adaptive.engine")
+
+
+class AdaptiveEngine:
+    """Orchestrates adaptive multi-depth offensive campaigns against ActShield defenses."""
+
+    def __init__(
+        self,
+        engine: Optional[OffensiveEngine] = None,
+        corpus: Optional[AttackCorpus] = None,
+        registry: Optional[TargetRegistry] = None,
+        validator: Optional[SafetyValidator] = None,
+        max_depth: int = 3,
+        branch_factor: int = 2,
+        seed: Optional[int] = 20260919,
+    ) -> None:
+        self.engine = engine or OffensiveEngine(corpus=corpus, registry=registry, validator=validator)
+        self.corpus = corpus or attack_corpus
+        self.registry = registry or target_registry
+        self.validator = validator or safety_validator
+        self.max_depth = max_depth
+        self.branch_factor = branch_factor
+        self.seed = seed
+        self.selector = AdaptiveAttackSelector(corpus=self.corpus, seed=seed)
+
+    def run_adaptive_campaign(
+        self,
+        family: Optional[str] = None,
+        attack_id: Optional[str] = None,
+        limit_seeds: Optional[int] = None,
+        target: Optional[AttackTarget] = None,
+        campaign_name: str = "Adaptive Offensive Campaign",
+    ) -> Tuple[List[OffensiveAttackResult], CampaignSummary, CampaignMemory]:
+        """Execute a full adaptive validation campaign."""
+        start_time = time.perf_counter()
+        target = target or self.registry.get("ActShield-demo")
+        campaign_id = f"camp_adapt_{datetime.now(timezone.utc).strftime('%Y%m%d_%H%M%S')}"
+        memory = CampaignMemory(campaign_id=campaign_id)
+
+        search_engine = BoundarySearchEngine(
+            engine=self.engine,
+            memory=memory,
+            max_depth=self.max_depth,
+            branch_factor=self.branch_factor,
+        )
+
+        seed_attacks = self.selector.select_seeds(family=family, attack_id=attack_id, limit=limit_seeds)
+        all_results: List[OffensiveAttackResult] = []
+
+        campaign = AttackCampaign(
+            campaign_id=campaign_id,
+            name=campaign_name,
+            objective=f"Adaptive exploration of defense boundaries (Max Depth: {self.max_depth})",
+            target=target,
+            attacks=seed_attacks,
+        )
+
+        for seed_attack in seed_attacks:
+            branch_results = search_engine.explore_boundary(
+                root_attack=seed_attack,
+                target=target,
+                campaign_id=campaign_id,
+            )
+            all_results.extend(branch_results)
+
+        duration_ms = (time.perf_counter() - start_time) * 1000
+
+        # Calculate enhanced scorecard
+        summary = CampaignSummary.from_results(
+            campaign=campaign,
+            results=all_results,
+            memory=memory,
+            seed=self.seed,
+            duration_ms=duration_ms,
+        )
+
+        return all_results, summary, memory
+
+    def export_dashboard_json(
+        self,
+        summary: CampaignSummary,
+        results: List[OffensiveAttackResult],
+        memory: CampaignMemory,
+        output_dir: Optional[str] = None,
+    ) -> Dict[str, str]:
+        """Export comprehensive dashboard-ready JSON artifacts."""
+        if output_dir:
+            out_path = pathlib.Path(output_dir)
+        else:
+            root = pathlib.Path(__file__).resolve().parent.parent.parent.parent.parent
+            out_path = root / "reports" / "phase5"
+
+        out_path.mkdir(parents=True, exist_ok=True)
+
+        # 1. Dashboard Master Package
+        dashboard_payload = {
+            "campaign": {
+                "campaign_id": summary.campaign_id,
+                "name": summary.name,
+                "target_id": summary.target_id,
+                "timestamp": summary.timestamp.isoformat(),
+                "seed": summary.campaign_seed,
+                "duration_ms": summary.duration_ms,
+            },
+            "coverage": {
+                "total_attacks": summary.total_attacks,
+                "attack_family_breakdown": summary.coverage_breakdown,
+                "unique_attack_variants": summary.unique_attack_variants,
+                "max_mutation_depth": summary.max_mutation_depth,
+                "avg_mutation_depth": summary.avg_mutation_depth,
+            },
+            "security": {
+                "blocked": summary.blocked,
+                "bypassed": summary.bypassed,
+                "block_rate_pct": summary.block_rate_pct,
+                "sensitive_actions_attempted": summary.sensitive_actions_attempted,
+                "sensitive_actions_executed": summary.sensitive_actions_executed,
+                "empirical_prevention_rate": summary.empirical_prevention_rate,
+                "ai_analysis_availability_pct": summary.ai_analysis_availability_pct,
+                "apiris_analysis_availability_pct": summary.apiris_analysis_availability_pct,
+                "defense_reasons_breakdown": summary.defense_reasons_breakdown,
+            },
+            "performance": {
+                "mean_latency_ms": summary.mean_latency_ms,
+                "p95_latency_ms": summary.p95_latency_ms,
+            },
+            "mutations": [n.to_dict() for n in memory.get_all_nodes()],
+            "bypasses": [n.to_dict() for n in memory.get_bypasses()],
+            "regressions": summary.regression_fixtures_generated,
+        }
+
+        dash_file = out_path / "adaptive_dashboard.json"
+        dash_file.write_text(json.dumps(dashboard_payload, indent=2), encoding="utf-8")
+
+        # 2. Markdown Summary
+        md_file = out_path / "adaptive_campaign_summary.md"
+        md_file.write_text(summary.to_markdown(), encoding="utf-8")
+
+        return {
+            "dashboard_json": str(dash_file),
+            "summary_md": str(md_file),
+        }
+
+

actshield/offensive/adaptive/attack_selector.py

@@ -0,0 +1,51 @@
+"""Adaptive attack selector providing deterministic seed selection across attack families."""
+
+import random
+from typing import List, Optional
+from actshield.offensive.attack import AttackCase, AttackType
+from actshield.offensive.corpus import AttackCorpus, attack_corpus
+
+
+class AdaptiveAttackSelector:
+    """Selects base seed attacks from the corpus for adaptive exploration."""
+
+    def __init__(self, corpus: Optional[AttackCorpus] = None, seed: Optional[int] = None) -> None:
+        self.corpus = corpus or attack_corpus
+        self.seed = seed
+        if seed is not None:
+            random.seed(seed)
+
+    def select_seeds(
+        self,
+        family: Optional[str] = None,
+        attack_id: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> List[AttackCase]:
+        """Select seed attacks matching criteria."""
+        all_attacks = self.corpus.get_all_attacks()
+
+        if attack_id:
+            found = self.corpus.get_attack(attack_id)
+            return [found] if found else []
+
+        if family:
+            fam_clean = family.lower().replace("-", "_")
+            filtered = [
+                a for a in all_attacks
+                if fam_clean in a.attack_type.value.lower() or fam_clean in a.attack_id.lower()
+            ]
+        else:
+            filtered = all_attacks
+
+        if self.seed is not None:
+            # Deterministic shuffle
+            rng = random.Random(self.seed)
+            shuffled = list(filtered)
+            rng.shuffle(shuffled)
+            filtered = shuffled
+
+        if limit and limit > 0:
+            return filtered[:limit]
+
+        return filtered
+

actshield/offensive/adaptive/boundary_search.py

@@ -0,0 +1,99 @@
+"""Boundary search engine executing bounded adaptive exploration of defense limits."""
+
+from typing import List, Optional, Tuple
+from actshield.offensive.attack import AttackCase
+from actshield.offensive.engine import OffensiveEngine
+from actshield.offensive.results import AttackStatus, OffensiveAttackResult
+from actshield.offensive.target import AttackTarget
+from actshield.offensive.adaptive.campaign_memory import CampaignMemory
+from actshield.offensive.adaptive.feedback import FeedbackAnalyzer
+from actshield.offensive.adaptive.mutation_planner import MutationPlanner
+
+
+class BoundarySearchEngine:
+    """Explores the decision boundary around an attack vector until bypass or max depth."""
+
+    def __init__(
+        self,
+        engine: OffensiveEngine,
+        memory: CampaignMemory,
+        max_depth: int = 3,
+        branch_factor: int = 2,
+        max_attempts_per_attack: int = 10,
+    ) -> None:
+        self.engine = engine
+        self.memory = memory
+        self.max_depth = max_depth
+        self.branch_factor = branch_factor
+        self.max_attempts_per_attack = max_attempts_per_attack
+
+    def explore_boundary(
+        self,
+        root_attack: AttackCase,
+        target: Optional[AttackTarget] = None,
+        campaign_id: Optional[str] = None,
+    ) -> List[OffensiveAttackResult]:
+        """Execute bounded adaptive exploration starting from root_attack."""
+        results: List[OffensiveAttackResult] = []
+        attempts = 0
+
+        # Queue items: (AttackCase, depth, parent_id, strategy_name)
+        queue: List[Tuple[AttackCase, int, Optional[str], str]] = [(root_attack, 0, None, "baseline")]
+
+        while queue and attempts < self.max_attempts_per_attack:
+            current_attack, depth, parent_id, strategy = queue.pop(0)
+            attempts += 1
+
+            # Get lineage so far
+            lineage_ids = [n.mutation_id for n in self.memory.get_lineage(parent_id)] if parent_id else []
+            lineage_ids.append(current_attack.attack_id)
+
+            # Execute attack through full security pipeline
+            res = self.engine.execute_attack(
+                attack=current_attack,
+                target=target,
+                campaign_id=campaign_id,
+                mutation_lineage=lineage_ids,
+            )
+            results.append(res)
+
+            # Record in campaign memory
+            self.memory.record_node(
+                mutation_id=current_attack.attack_id,
+                root_attack_id=root_attack.attack_id,
+                parent_id=parent_id,
+                strategy=strategy,
+                depth=depth,
+                input_payload=root_attack.payload,
+                output_payload=current_attack.payload,
+                defense_reason=res.execution_evidence.policy_reason,
+                decision=res.actual_decision,
+                status=res.status.value,
+                sensitive_executions=res.execution_evidence.sensitive_db_calls,
+                latency_ms=res.latency_ms,
+            )
+
+            # INVARIANT: If bypass is discovered, STOP exploring this branch immediately!
+            if res.bypassed:
+                break
+
+            # If not bypassed and depth < max_depth, generate targeted mutations
+            if depth < self.max_depth:
+                feedback = FeedbackAnalyzer.analyze(res)
+                next_mutations = MutationPlanner.plan_next_mutations(
+                    parent_attack=current_attack,
+                    feedback=feedback,
+                    depth=depth + 1,
+                    branch_factor=self.branch_factor,
+                )
+
+                for mut_case in next_mutations:
+                    queue.append((
+                        mut_case,
+                        depth + 1,
+                        current_attack.attack_id,
+                        mut_case.mutation_strategy or "mutation",
+                    ))
+
+        return results
+

actshield/offensive/adaptive/campaign_memory.py

@@ -0,0 +1,123 @@
+"""Campaign Memory and Mutation Lineage Graph for Adaptive Offensive Validation."""
+
+import hashlib
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+
+
+class MutationNode(BaseModel):
+    """Represents a single node in an adaptive attack mutation lineage tree."""
+
+    mutation_id: str = Field(..., description="Unique ID for this mutation attempt")
+    parent_id: Optional[str] = Field(default=None, description="Parent attack/mutation ID")
+    root_attack_id: str = Field(..., description="The original baseline attack ID")
+    strategy: str = Field(default="baseline", description="Mutation strategy applied")
+    depth: int = Field(default=0, description="Mutation depth from baseline root (0 = root)")
+    
+    input_payload: str = Field(default="", description="Input payload before mutation")
+    output_payload: str = Field(default="", description="Output payload after mutation")
+    input_hash: str = Field(default="", description="SHA-256 hash of input payload")
+    output_hash: str = Field(default="", description="SHA-256 hash of output payload")
+    
+    defense_reason: str = Field(default="", description="Defensive policy reason code rendered")
+    decision: str = Field(default="UNKNOWN", description="Policy decision (BLOCK/ALLOW/etc.)")
+    status: str = Field(default="PASS", description="Attack status (PASS/BYPASS/ERROR/REFUSED)")
+    sensitive_executions: int = Field(default=0, description="Count of unauthorized sensitive sink calls")
+    latency_ms: float = Field(default=0.0, description="Execution latency in milliseconds")
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+    @staticmethod
+    def compute_hash(text: str) -> str:
+        """Compute 8-char truncated SHA-256 hash of text."""
+        return hashlib.sha256(text.encode("utf-8")).hexdigest()[:12]
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert node to dictionary."""
+        return self.model_dump(mode="json")
+
+
+class CampaignMemory:
+    """Stores the full adaptive exploration graph, lineage trees, and defense responses."""
+
+    def __init__(self, campaign_id: Optional[str] = None) -> None:
+        self.campaign_id = campaign_id or f"camp_mem_{datetime.now(timezone.utc).strftime('%Y%m%d_%H%M%S')}"
+        self.nodes: Dict[str, MutationNode] = {}
+        self.children_map: Dict[str, List[str]] = {}
+        self.bypasses: List[str] = []
+
+    def record_node(
+        self,
+        mutation_id: str,
+        root_attack_id: str,
+        parent_id: Optional[str] = None,
+        strategy: str = "baseline",
+        depth: int = 0,
+        input_payload: str = "",
+        output_payload: str = "",
+        defense_reason: str = "",
+        decision: str = "UNKNOWN",
+        status: str = "PASS",
+        sensitive_executions: int = 0,
+        latency_ms: float = 0.0,
+    ) -> MutationNode:
+        """Record an attack attempt into campaign memory."""
+        node = MutationNode(
+            mutation_id=mutation_id,
+            parent_id=parent_id,
+            root_attack_id=root_attack_id,
+            strategy=strategy,
+            depth=depth,
+            input_payload=input_payload,
+            output_payload=output_payload,
+            input_hash=MutationNode.compute_hash(input_payload),
+            output_hash=MutationNode.compute_hash(output_payload),
+            defense_reason=defense_reason,
+            decision=decision,
+            status=status,
+            sensitive_executions=sensitive_executions,
+            latency_ms=latency_ms,
+        )
+        self.nodes[mutation_id] = node
+
+        if parent_id:
+            if parent_id not in self.children_map:
+                self.children_map[parent_id] = []
+            self.children_map[parent_id].append(mutation_id)
+
+        if status == "BYPASS" or sensitive_executions > 0:
+            if mutation_id not in self.bypasses:
+                self.bypasses.append(mutation_id)
+
+        return node
+
+    def get_lineage(self, attack_or_mutation_id: str) -> List[MutationNode]:
+        """Return root-to-leaf sequence of MutationNodes for the given attack/mutation ID."""
+        lineage: List[MutationNode] = []
+        curr_id: Optional[str] = attack_or_mutation_id
+
+        while curr_id and curr_id in self.nodes:
+            node = self.nodes[curr_id]
+            lineage.append(node)
+            curr_id = node.parent_id
+
+        lineage.reverse()
+        return lineage
+
+    def get_all_nodes(self) -> List[MutationNode]:
+        """Return all recorded mutation nodes."""
+        return list(self.nodes.values())
+
+    def get_bypasses(self) -> List[MutationNode]:
+        """Return all nodes where a bypass was discovered."""
+        return [self.nodes[bid] for bid in self.bypasses if bid in self.nodes]
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Export campaign memory to dictionary."""
+        return {
+            "campaign_id": self.campaign_id,
+            "total_nodes": len(self.nodes),
+            "total_bypasses": len(self.bypasses),
+            "nodes": [n.to_dict() for n in self.nodes.values()],
+            "bypasses": self.bypasses,
+        }