actshield 0.9.0__py3-none-any.whl

actshield/offensive/adaptive/feedback.py

@@ -0,0 +1,84 @@
+"""Defensive feedback analyzer for adaptive offensive exploration."""
+
+from enum import Enum
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+
+from actshield.offensive.results import AttackStatus, OffensiveAttackResult
+
+
+class DefenseCategory(str, Enum):
+    """Categorization of defensive enforcement mechanisms."""
+    TAINT_GUARD = "TAINT_GUARD"                     # Blocked because tainted context reached a sensitive sink
+    AUTHORITY_GUARD = "AUTHORITY_GUARD"             # Blocked due to missing capability or exceeded delegation
+    INTENT_GUARD = "INTENT_GUARD"                   # Blocked due to divergence from task original intent
+    TRUST_GUARD = "TRUST_GUARD"                     # Blocked because agent trust level is UNTRUSTED
+    BENIGN_ALLOW = "BENIGN_ALLOW"                   # Allowed under standard policy
+    UNKNOWN_DEFENSE = "UNKNOWN_DEFENSE"             # Other or unclassified
+
+
+class DefenseFeedback(BaseModel):
+    """Structured analytical feedback derived from previous defense response."""
+
+    attack_id: str
+    decision: str
+    reason_code: str
+    explanation: str
+    defense_category: DefenseCategory
+    bypassed: bool
+    sensitive_executions: int
+    
+    # Adaptive guidance
+    suggested_mutation_strategies: List[str] = Field(default_factory=list)
+    boundary_distance_estimate: float = Field(default=1.0, description="1.0 = deeply blocked, 0.0 = bypassed")
+
+
+class FeedbackAnalyzer:
+    """Analyzes offensive attack results to guide subsequent mutation planning."""
+
+    @staticmethod
+    def analyze(result: OffensiveAttackResult) -> DefenseFeedback:
+        """Extract actionable feedback from an attack result."""
+        actual_action = result.actual_decision
+        reason = result.execution_evidence.policy_reason or ""
+        bypassed = result.bypassed
+        sens_exec = result.execution_evidence.sensitive_db_calls
+
+        # Classify defense
+        if bypassed or actual_action == "ALLOW":
+            category = DefenseCategory.BENIGN_ALLOW
+            strategies = []
+            dist = 0.0
+        elif "TAINT" in reason or "tainted" in reason.lower():
+            category = DefenseCategory.TAINT_GUARD
+            strategies = ["context_repackaging", "nested_roleplay", "base64_encoding", "unicode_homoglyph"]
+            dist = 0.7
+        elif "AUTHORITY" in reason or "CAPABILITY" in reason or "DELEGATION" in reason:
+            category = DefenseCategory.AUTHORITY_GUARD
+            strategies = ["authority_impersonation", "semantic_reframing", "delimiter_injection"]
+            dist = 0.8
+        elif "INTENT" in reason or "intent" in reason.lower():
+            category = DefenseCategory.INTENT_GUARD
+            strategies = ["semantic_reframing", "typo_injection", "casing_randomization"]
+            dist = 0.6
+        elif "UNTRUSTED" in reason:
+            category = DefenseCategory.TRUST_GUARD
+            strategies = ["authority_impersonation", "nested_roleplay"]
+            dist = 0.9
+        else:
+            category = DefenseCategory.UNKNOWN_DEFENSE
+            strategies = ["semantic_reframing", "base64_encoding", "nested_roleplay"]
+            dist = 0.75
+
+        return DefenseFeedback(
+            attack_id=result.attack_id,
+            decision=actual_action,
+            reason_code=reason,
+            explanation=result.error_message or reason,
+            defense_category=category,
+            bypassed=bypassed,
+            sensitive_executions=sens_exec,
+            suggested_mutation_strategies=strategies,
+            boundary_distance_estimate=dist,
+        )
+

actshield/offensive/adaptive/mutation_planner.py

@@ -0,0 +1,57 @@
+"""Adaptive mutation planner composing multi-step transformations based on defensive feedback."""
+
+from typing import List, Optional
+from actshield.offensive.attack import AttackCase, SafetyClass
+from actshield.offensive.mutation import MutationEngine, MutationStrategy
+from actshield.offensive.adaptive.feedback import DefenseFeedback
+
+
+class MutationPlanner:
+    """Plans and composes targeted mutations based on previous defense reasons."""
+
+    # Map feedback suggested strategy names to MutationStrategy enums
+    STRATEGY_MAP = {
+        "context_repackaging": MutationStrategy.CONTEXT_PLACEMENT,
+        "nested_roleplay": MutationStrategy.ROLEPLAY_FRAMING,
+        "base64_encoding": MutationStrategy.ENCODING_OBSCURE,
+        "unicode_homoglyph": MutationStrategy.ENCODING_OBSCURE,
+        "authority_impersonation": MutationStrategy.AUTHORITY_FABRICATION,
+        "semantic_reframing": MutationStrategy.WORDING_VARIATION,
+        "delimiter_injection": MutationStrategy.DELIMITER_STUFFING,
+        "typo_injection": MutationStrategy.WORDING_VARIATION,
+        "casing_randomization": MutationStrategy.WORDING_VARIATION,
+        "urgency_escalation": MutationStrategy.URGENCY_INJECTION,
+    }
+
+    @classmethod
+    def plan_next_mutations(
+        cls,
+        parent_attack: AttackCase,
+        feedback: DefenseFeedback,
+        depth: int,
+        branch_factor: int = 2,
+    ) -> List[AttackCase]:
+        """Generate next generation of mutated attack cases tailored to previous defense response."""
+        planned_cases: List[AttackCase] = []
+        suggested = feedback.suggested_mutation_strategies or ["semantic_reframing", "nested_roleplay"]
+
+        for idx, strat_name in enumerate(suggested[:branch_factor], 1):
+            strategy_enum = cls.STRATEGY_MAP.get(strat_name, MutationStrategy.WORDING_VARIATION)
+            
+            # Apply transformation
+            mutated_cases = MutationEngine.mutate(parent_attack, strategy=strategy_enum, count=1)
+            if mutated_cases:
+                mut_case = mutated_cases[0]
+                mut_id = f"{parent_attack.attack_id}_d{depth}_{strategy_enum.value[:4]}_{idx:02d}"
+                
+                # Enrich metadata
+                mut_case = mut_case.model_copy(update={
+                    "attack_id": mut_id,
+                    "mutation_of": parent_attack.attack_id,
+                    "mutation_strategy": strategy_enum.value,
+                    "safety_class": SafetyClass.LOCAL_SYNTHETIC,
+                })
+                planned_cases.append(mut_case)
+
+        return planned_cases
+

actshield/offensive/attack.py

@@ -0,0 +1,78 @@
+"""Attack models and schemas for ActShield offensive validation."""
+
+from enum import Enum
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+
+from actshield.tracing.correlation import generate_id
+
+
+class AttackType(str, Enum):
+    """Standardized classification of offensive attack vectors."""
+    INDIRECT_PROMPT_INJECTION = "indirect_prompt_injection"
+    DIRECT_PROMPT_INJECTION = "direct_prompt_injection"
+    AUTHORITY_IMPERSONATION = "authority_impersonation"
+    AUTHORITY_ESCALATION = "authority_escalation"
+    TOOL_POISONING = "tool_poisoning"
+    MCP_SERVER_POISONING = "mcp_server_poisoning"
+    CONTEXT_MANIPULATION = "context_manipulation"
+    TAINT_LAUNDERING = "taint_laundering"
+    DELEGATION_ESCALATION = "delegation_escalation"
+    MULTI_HOP_ESCALATION = "multi_hop_escalation"
+    DATA_EXFILTRATION = "data_exfiltration"
+    INTENT_DRIFT = "intent_drift"
+    JAILBREAK = "jailbreak"
+    CUSTOM = "custom"
+
+
+class SafetyClass(str, Enum):
+    """Execution safety classification."""
+    LOCAL_SYNTHETIC = "LOCAL_SYNTHETIC"
+    SANDBOX_MOCK = "SANDBOX_MOCK"
+    UNSAFE_EXTERNAL = "UNSAFE_EXTERNAL"
+
+
+class ExpectedBehavior(str, Enum):
+    """Expected security outcome when the attack is injected."""
+    BLOCK = "BLOCK"
+    ALLOW = "ALLOW"
+    HITL_REQUIRED = "HITL_REQUIRED"
+    SANITIZED = "SANITIZED"
+
+
+class AttackCase(BaseModel):
+    """Structured offensive test case designed to validate security boundaries."""
+
+    attack_id: str = Field(default_factory=lambda: generate_id("atk"), description="Unique attack identifier")
+    attack_type: AttackType = Field(default=AttackType.CUSTOM, description="Classification of attack vector")
+    name: str = Field(default="", description="Human-readable name of the attack")
+    description: str = Field(default="", description="Detailed description of attack objective and mechanism")
+    
+    # Injection details
+    entry_point: str = Field(default="mcp_response", description="Entry point (e.g. 'mcp_response', 'http_request', 'tool_output', 'user_input')")
+    target_agent: str = Field(default="DataAgent", description="Target acting agent name in the simulation")
+    payload: str = Field(default="", description="The adversarial payload data injected into the context")
+    
+    # Target execution parameters
+    target_tool: Optional[str] = Field(default=None, description="The tool the attack attempts to cause execution of")
+    target_resource: Optional[str] = Field(default=None, description="Target resource name/sensitivity")
+    required_capability: Optional[str] = Field(default=None, description="Capability needed to execute target tool")
+    tool_arguments: Dict[str, Any] = Field(default_factory=dict, description="Arguments passed to target tool if triggered")
+    
+    # Preconditions and Context
+    task_intent: str = Field(default="Standard authorized operation", description="The legitimate original user intent")
+    preconditions: Dict[str, Any] = Field(default_factory=dict, description="Preconditions required for attack setup")
+    context_taint: str = Field(default="TAINTED", description="Taint state assigned to injected payload")
+    
+    # Expectations and Safety
+    expected_behavior: ExpectedBehavior = Field(default=ExpectedBehavior.BLOCK, description="Expected defense outcome")
+    severity: str = Field(default="HIGH", description="Assessed threat severity (LOW/MEDIUM/HIGH/CRITICAL)")
+    safety_class: SafetyClass = Field(default=SafetyClass.LOCAL_SYNTHETIC, description="Safety classification")
+    
+    # Mutation Lineage
+    mutation_of: Optional[str] = Field(default=None, description="Base attack ID if this is a mutated variant")
+    mutation_strategy: Optional[str] = Field(default=None, description="Mutation strategy applied to generate this case")
+    
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Additional contextual metadata")
+
+

actshield/offensive/campaign.py

@@ -0,0 +1,219 @@
+"""Attack campaign definitions and scorecard aggregation."""
+
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+
+from actshield.offensive.attack import AttackCase
+from actshield.offensive.results import AttackStatus, OffensiveAttackResult
+from actshield.offensive.target import AttackTarget, target_registry
+from actshield.tracing.correlation import generate_id
+
+
+class AttackCampaign(BaseModel):
+    """A collection of offensive attack validations executed as a cohesive campaign."""
+
+    campaign_id: str = Field(default_factory=lambda: generate_id("camp"), description="Unique campaign ID")
+    name: str = Field(..., description="Human-readable campaign title")
+    objective: str = Field(..., description="Campaign validation objective")
+    target: AttackTarget = Field(..., description="Target system under validation")
+    attacks: List[AttackCase] = Field(default_factory=list, description="List of attack cases in campaign")
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+class CampaignSummary(BaseModel):
+    """Empirical security scorecard and metrics aggregated from a completed campaign."""
+
+    campaign_id: str = Field(..., description="Campaign ID")
+    name: str = Field(..., description="Campaign title")
+    target_id: str = Field(..., description="Target system ID")
+    
+    # Attack & Attempt Counts
+    total_attacks: int = Field(default=0)
+    blocked: int = Field(default=0)
+    bypassed: int = Field(default=0)
+    refused: int = Field(default=0)
+    errors: int = Field(default=0)
+    unique_attack_variants: int = Field(default=0)
+    
+    # Hard Empirical Metrics
+    sensitive_actions_attempted: int = Field(default=0, description="Total sensitive tool invocations attempted")
+    sensitive_actions_prevented: int = Field(default=0, description="Total sensitive tool invocations blocked")
+    sensitive_actions_executed: int = Field(default=0, description="Total unauthorized sensitive executions (Bypasses)")
+    empirical_prevention_rate: float = Field(default=1.0, description="1 - (executed / attempted)")
+    
+    # Rates & Latency
+    block_rate_pct: float = Field(default=0.0, description="Percentage of unauthorized attacks successfully blocked")
+    sensitive_prevention_rate_pct: float = Field(default=100.0, description="Rate of sensitive sink protection")
+    mean_latency_ms: float = Field(default=0.0)
+    p95_latency_ms: float = Field(default=0.0)
+    duration_ms: float = Field(default=0.0)
+    campaign_seed: Optional[int] = Field(default=None)
+
+    # Adaptive & Lineage Metrics
+    max_mutation_depth: int = Field(default=0)
+    avg_mutation_depth: float = Field(default=0.0)
+    regression_fixtures_generated: int = Field(default=0)
+
+    # Pipeline Availability
+    ai_analysis_availability_pct: float = Field(default=100.0)
+    apiris_analysis_availability_pct: float = Field(default=100.0)
+    
+    # Coverage Breakdown
+    coverage_breakdown: Dict[str, Dict[str, int]] = Field(default_factory=dict)
+    defense_reasons_breakdown: Dict[str, int] = Field(default_factory=dict)
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+    @classmethod
+    def from_results(
+        cls,
+        campaign: AttackCampaign,
+        results: List[OffensiveAttackResult],
+        memory: Optional[Any] = None,
+        seed: Optional[int] = None,
+        duration_ms: float = 0.0,
+    ) -> "CampaignSummary":
+        """Aggregate results into an empirical CampaignSummary."""
+        total = len(results)
+        if total == 0:
+            return cls(
+                campaign_id=campaign.campaign_id,
+                name=campaign.name,
+                target_id=campaign.target.target_id,
+                campaign_seed=seed,
+                duration_ms=duration_ms,
+            )
+
+        blocked = sum(1 for r in results if r.blocked or r.status == AttackStatus.PASS)
+        bypassed = sum(1 for r in results if r.bypassed or r.status == AttackStatus.BYPASS)
+        refused = sum(1 for r in results if r.status == AttackStatus.REFUSED)
+        errors = sum(1 for r in results if r.status == AttackStatus.ERROR)
+
+        sens_exec = sum(r.execution_evidence.sensitive_db_calls for r in results if r.execution_evidence)
+        sens_prev = sum(1 for r in results if r.blocked or r.status == AttackStatus.PASS)
+        sens_attempted = sens_prev + sens_exec
+
+        # Empirical prevention rate = 1 - (executed / attempted)
+        if sens_attempted > 0:
+            emp_rate = round(1.0 - (sens_exec / sens_attempted), 4)
+        else:
+            emp_rate = 1.0
+
+        # Latencies
+        lats = sorted([r.latency_ms for r in results])
+        mean_lat = sum(lats) / total if total > 0 else 0.0
+        p95_idx = int(total * 0.95)
+        p95_lat = lats[min(p95_idx, total - 1)] if total > 0 else 0.0
+
+        # Coverage breakdown by attack_type
+        coverage: Dict[str, Dict[str, int]] = {}
+        defense_reasons: Dict[str, int] = {}
+        ai_available_count = 0
+        apiris_available_count = 0
+
+        for r in results:
+            atype = r.attack_type.value if hasattr(r.attack_type, 'value') else str(r.attack_type)
+            if atype not in coverage:
+                coverage[atype] = {"total": 0, "blocked": 0, "bypassed": 0}
+            coverage[atype]["total"] += 1
+            if r.blocked or r.status == AttackStatus.PASS:
+                coverage[atype]["blocked"] += 1
+            if r.bypassed or r.status == AttackStatus.BYPASS:
+                coverage[atype]["bypassed"] += 1
+
+            reason = r.execution_evidence.policy_reason or "UNKNOWN"
+            defense_reasons[reason] = defense_reasons.get(reason, 0) + 1
+
+            if r.ai_analysis and r.ai_analysis.get("status") != "UNAVAILABLE":
+                ai_available_count += 1
+            if r.apiris_analysis and r.apiris_analysis.get("status") != "UNAVAILABLE":
+                apiris_available_count += 1
+
+        block_rate = round((blocked / total) * 100, 1) if total > 0 else 0.0
+        prev_rate = round(((total - bypassed) / total) * 100, 1) if total > 0 else 100.0
+
+        ai_avail_pct = round((ai_available_count / total) * 100, 1) if total > 0 else 100.0
+        apiris_avail_pct = round((apiris_available_count / total) * 100, 1) if total > 0 else 100.0
+
+        # Memory / Lineage metrics
+        max_depth = 0
+        avg_depth = 0.0
+        reg_count = bypassed
+        if memory and hasattr(memory, "nodes"):
+            all_nodes = list(memory.nodes.values())
+            if all_nodes:
+                depths = [n.depth for n in all_nodes]
+                max_depth = max(depths)
+                avg_depth = round(sum(depths) / len(depths), 2)
+            reg_count = len(getattr(memory, "bypasses", [])) or bypassed
+
+        return cls(
+            campaign_id=campaign.campaign_id,
+            name=campaign.name,
+            target_id=campaign.target.target_id,
+            total_attacks=total,
+            blocked=blocked,
+            bypassed=bypassed,
+            refused=refused,
+            errors=errors,
+            unique_attack_variants=len(set(r.attack_id for r in results)),
+            sensitive_actions_attempted=sens_attempted,
+            sensitive_actions_prevented=sens_prev,
+            sensitive_actions_executed=sens_exec,
+            empirical_prevention_rate=emp_rate,
+            block_rate_pct=block_rate,
+            sensitive_prevention_rate_pct=prev_rate,
+            mean_latency_ms=round(mean_lat, 2),
+            p95_latency_ms=round(p95_lat, 2),
+            duration_ms=round(duration_ms, 2),
+            campaign_seed=seed,
+            max_mutation_depth=max_depth,
+            avg_mutation_depth=avg_depth,
+            regression_fixtures_generated=reg_count,
+            ai_analysis_availability_pct=ai_avail_pct,
+            apiris_analysis_availability_pct=apiris_avail_pct,
+            coverage_breakdown=coverage,
+            defense_reasons_breakdown=defense_reasons,
+        )
+
+    def to_markdown(self) -> str:
+        """Format summary into structured Markdown."""
+        lines = [
+            "# ActShield Adaptive Offensive Validation Scorecard",
+            "",
+            f"- **Campaign ID**: `{self.campaign_id}`",
+            f"- **Target System**: `{self.target_id}`",
+            f"- **Campaign Seed**: `{self.campaign_seed}`",
+            f"- **Total Attack Executions**: {self.total_attacks} (Unique Variants: {self.unique_attack_variants})",
+            f"- **Attacks Blocked**: {self.blocked} ({self.block_rate_pct}%)",
+            f"- **Attacks Bypassed**: {self.bypassed}",
+            f"- **Sensitive Database Executions**: {self.sensitive_actions_executed}",
+            f"- **Empirical Prevention Rate**: {self.empirical_prevention_rate * 100:.1f}%",
+            f"- **Max Mutation Depth**: {self.max_mutation_depth} (Average: {self.avg_mutation_depth})",
+            f"- **Mean Latency**: {self.mean_latency_ms} ms (p95: {self.p95_latency_ms} ms)",
+            f"- **Pipeline Availability**: AI Secura ({self.ai_analysis_availability_pct}%) | APIRIS ({self.apiris_analysis_availability_pct}%)",
+            "",
+            "## Attack Family Coverage Breakdown",
+            "",
+            "| Attack Type | Total | Blocked | Bypassed |",
+            "|---|---|---|---|",
+        ]
+
+        for atype, stats in self.coverage_breakdown.items():
+            lines.append(f"| `{atype}` | {stats['total']} | {stats['blocked']} | {stats['bypassed']} |")
+
+        lines.extend([
+            "",
+            "## Defense Reasons Breakdown",
+            "",
+            "| Defense Reason Code | Count |",
+            "|---|---|",
+        ])
+
+        for reason, count in self.defense_reasons_breakdown.items():
+            lines.append(f"| `{reason}` | {count} |")
+
+        return "\n".join(lines)
+
+

actshield/offensive/corpus.py

@@ -0,0 +1,155 @@
+"""Attack corpus loader managing baseline fixtures, attack families, and regression cases."""
+
+import json
+import pathlib
+from typing import Dict, List, Optional
+
+from actshield.offensive.attack import AttackCase, AttackType, ExpectedBehavior, SafetyClass
+from actshield.offensive.strategies import (
+    PromptInjectionStrategy,
+    AuthorityEscalationStrategy,
+    ToolPoisoningStrategy,
+    ContextManipulationStrategy,
+    MCPInjectionStrategy,
+    DataExfiltrationStrategy,
+    DelegationEscalationStrategy,
+)
+from actshield.offensive.target import AttackTarget, target_registry
+
+
+class AttackCorpus:
+    """Central repository for loading, organizing, and persisting attack fixtures."""
+
+    def __init__(
+        self,
+        fixtures_dir: Optional[pathlib.Path] = None,
+        regressions_dir: Optional[pathlib.Path] = None,
+    ) -> None:
+        # Default paths
+        root = pathlib.Path(__file__).resolve().parent.parent.parent.parent
+        self.fixtures_dir = fixtures_dir or (root / "examples" / "attacks")
+        self.regressions_dir = regressions_dir or (root / "examples" / "attacks" / "regressions")
+        self.regressions_dir.mkdir(parents=True, exist_ok=True)
+
+    def load_baseline_fixtures(self) -> List[AttackCase]:
+        """Load the 5 existing baseline attack fixtures from examples/attacks/."""
+        cases: List[AttackCase] = []
+        if not self.fixtures_dir.exists():
+            return cases
+
+        for json_path in sorted(self.fixtures_dir.glob("*.json")):
+            try:
+                with open(json_path, "r", encoding="utf-8") as f:
+                    data = json.load(f)
+                
+                # Map legacy format to AttackCase
+                atype_str = data.get("attack_type", "custom")
+                try:
+                    atype = AttackType(atype_str)
+                except ValueError:
+                    atype = AttackType.CUSTOM
+
+                case = AttackCase(
+                    attack_id=data.get("attack_id", json_path.stem),
+                    name=data.get("attack_id", json_path.stem).replace("_", " ").title(),
+                    attack_type=atype,
+                    description=data.get("description", "Baseline attack fixture"),
+                    entry_point=data.get("entry_point", "mcp_response"),
+                    target_agent=data.get("target_agent", "DataAgent"),
+                    payload=data.get("payload", ""),
+                    target_tool=data.get("target_capability", "customer_db.read"),
+                    target_resource="customer_pii_vault",
+                    expected_behavior=ExpectedBehavior.BLOCK if data.get("expected_decision") == "BLOCK" else ExpectedBehavior.ALLOW,
+                    severity="HIGH",
+                    safety_class=SafetyClass.LOCAL_SYNTHETIC,
+                )
+                cases.append(case)
+            except Exception:
+                pass
+
+        return cases
+
+    def generate_full_family_corpus(self, target: Optional[AttackTarget] = None) -> List[AttackCase]:
+        """Generate comprehensive attack cases spanning all core attack families."""
+        target = target or target_registry.get("ActShield-demo")
+        all_cases: List[AttackCase] = []
+
+        # 1. Include baseline fixtures
+        all_cases.extend(self.load_baseline_fixtures())
+
+        # 2. Generate from all strategies
+        strategies = [
+            PromptInjectionStrategy(),
+            AuthorityEscalationStrategy(),
+            ToolPoisoningStrategy(),
+            ContextManipulationStrategy(),
+            MCPInjectionStrategy(),
+            DataExfiltrationStrategy(),
+            DelegationEscalationStrategy(),
+        ]
+
+        for strat in strategies:
+            strat_cases = strat.generate(target, count=5)
+            # Avoid duplicate IDs
+            for c in strat_cases:
+                if not any(existing.attack_id == c.attack_id for existing in all_cases):
+                    all_cases.append(c)
+
+        return all_cases
+
+    def get_all_attacks(self, target: Optional[AttackTarget] = None) -> List[AttackCase]:
+        """Convenience alias returning the full baseline and generated attack corpus."""
+        return self.generate_full_family_corpus(target=target)
+
+    def get_regression_attacks(self) -> List[AttackCase]:
+        """Convenience alias returning all regression attack cases."""
+        return self.load_regression_cases()
+
+    def get_attack(self, attack_id: str) -> Optional[AttackCase]:
+        """Retrieve a specific attack case by ID from full corpus or regression store."""
+        for a in self.get_all_attacks():
+            if a.attack_id == attack_id:
+                return a
+        for r in self.get_regression_attacks():
+            if r.attack_id == attack_id:
+                return r
+        return None
+
+    def get_attacks_by_type(self, attack_type: AttackType) -> List[AttackCase]:
+        """Retrieve all attack cases matching a specific AttackType."""
+        return [a for a in self.get_all_attacks() if a.attack_type == attack_type]
+
+    def save_regression_case(self, attack: AttackCase, reason: str = "Bypass detected") -> pathlib.Path:
+        """Persist a discovered bypass attack case to permanent regression fixtures."""
+        self.regressions_dir.mkdir(parents=True, exist_ok=True)
+        file_path = self.regressions_dir / f"{attack.attack_id}.json"
+        
+        data = attack.model_dump(mode="json")
+        data["regression_reason"] = reason
+        
+        with open(file_path, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+            
+        return file_path
+
+    def load_regression_cases(self) -> List[AttackCase]:
+        """Load all permanent regression attack fixtures."""
+        regressions: List[AttackCase] = []
+        if not self.regressions_dir.exists():
+            return regressions
+
+        for json_path in sorted(self.regressions_dir.glob("*.json")):
+            try:
+                with open(json_path, "r", encoding="utf-8") as f:
+                    data = json.load(f)
+                regressions.append(AttackCase(**data))
+            except Exception:
+                pass
+
+        return regressions
+
+
+# Global default corpus instance
+attack_corpus = AttackCorpus()
+
+