crprotocol 2.0.0__py3-none-any.whl

crp/security/embedding_defense.py

@@ -0,0 +1,161 @@
+# Copyright © 2025 Constantinos Vidiniotis. All rights reserved.
+# Licensed under Elastic License 2.0 — see LICENSE.md for details.
+"""Embedding defense — SQ8 quantization, XOR salting, no export (§7.11).
+
+Protects stored embeddings from extraction:
+- SQ8 quantization: float32 → int8 (reduces precision, saves memory)
+- XOR salting: 4-byte salt per embedding (masks raw values)
+- No embedding export: export_state() exports text only
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class ProtectedEmbedding:
+    """Embedding with SQ8 quantization and XOR salt applied."""
+
+    quantized: bytes  # SQ8 int8 values
+    salt: bytes  # 4-byte XOR salt
+    dimensions: int
+    scale: float  # quantization scale factor
+    zero_point: float  # quantization zero point
+
+    def to_dict(self) -> dict[str, Any]:
+        import base64
+        return {
+            "quantized": base64.b64encode(self.quantized).decode(),
+            "salt": base64.b64encode(self.salt).decode(),
+            "dimensions": self.dimensions,
+            "scale": self.scale,
+            "zero_point": self.zero_point,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ProtectedEmbedding:
+        import base64
+        return cls(
+            quantized=base64.b64decode(data["quantized"]),
+            salt=base64.b64decode(data["salt"]),
+            dimensions=data["dimensions"],
+            scale=data.get("scale", 1.0),
+            zero_point=data.get("zero_point", 0.0),
+        )
+
+
+class EmbeddingDefense:
+    """SQ8 quantization + XOR salting for embedding protection (§7.11).
+
+    Usage:
+        defense = EmbeddingDefense()
+        protected = defense.protect([0.1, 0.2, -0.3, ...])
+        recovered = defense.recover(protected)
+        # recovered ≈ original (within quantization error)
+
+        # export_state: embeddings are stripped
+        safe_data = defense.strip_embeddings_for_export(state_dict)
+    """
+
+    def __init__(self, salt: bytes | None = None) -> None:
+        # Default: random 4-byte salt (§6H.2)
+        self._default_salt = salt or os.urandom(4)
+
+    def protect(
+        self,
+        embedding: list[float],
+        salt: bytes | None = None,
+    ) -> ProtectedEmbedding:
+        """Apply SQ8 quantization + XOR salting (§6H.1, §6H.2).
+
+        SQ8: Maps float32 range [min, max] → int8 [-128, 127].
+        XOR: Applies 4-byte repeating XOR mask to quantized bytes.
+        """
+        if not embedding:
+            return ProtectedEmbedding(
+                quantized=b"", salt=salt or self._default_salt,
+                dimensions=0, scale=1.0, zero_point=0.0,
+            )
+
+        use_salt = salt or self._default_salt
+
+        # SQ8 quantization (§6H.1)
+        min_val = min(embedding)
+        max_val = max(embedding)
+        val_range = max_val - min_val
+        if val_range == 0:
+            val_range = 1.0  # avoid division by zero
+
+        scale = val_range / 255.0  # map to uint8 range, then shift to int8
+        zero_point = min_val
+
+        quantized = bytearray(len(embedding))
+        for i, v in enumerate(embedding):
+            # Quantize to int8 [-128, 127]
+            q = round((v - zero_point) / scale) - 128
+            q = max(-128, min(127, q))
+            quantized[i] = q & 0xFF  # store as unsigned byte
+
+        # XOR salting (§6H.2)
+        salted = bytearray(len(quantized))
+        salt_len = len(use_salt)
+        for i, b in enumerate(quantized):
+            salted[i] = b ^ use_salt[i % salt_len]
+
+        return ProtectedEmbedding(
+            quantized=bytes(salted),
+            salt=use_salt,
+            dimensions=len(embedding),
+            scale=scale,
+            zero_point=zero_point,
+        )
+
+    def recover(self, protected: ProtectedEmbedding) -> list[float]:
+        """Recover embedding from SQ8 + XOR protected form.
+
+        Returns approximate original values (quantization introduces error).
+        """
+        if protected.dimensions == 0:
+            return []
+
+        # Remove XOR salt
+        salt_len = len(protected.salt)
+        desalted = bytearray(len(protected.quantized))
+        for i, b in enumerate(protected.quantized):
+            desalted[i] = b ^ protected.salt[i % salt_len]
+
+        # Dequantize from int8
+        result: list[float] = []
+        for b in desalted:
+            # Convert unsigned byte back to signed int8
+            q = b if b < 128 else b - 256
+            # Reverse quantization
+            v = (q + 128) * protected.scale + protected.zero_point
+            result.append(v)
+
+        return result
+
+    @staticmethod
+    def strip_embeddings_for_export(state_dict: dict[str, Any]) -> dict[str, Any]:
+        """Strip all embeddings from state dict for export (§6H.3).
+
+        export_state() must export text only — no embeddings.
+        """
+        import copy
+        safe = copy.deepcopy(state_dict)
+
+        # Strip from facts
+        facts = safe.get("warm_store", {}).get("facts", {})
+        for _fid, fdata in facts.items():
+            fdata.pop("embedding", None)
+            fdata.pop("protected_embedding", None)
+            fdata["has_embedding"] = False
+
+        # Strip any top-level embedding data
+        safe.pop("embeddings", None)
+        safe.pop("ann_index", None)
+
+        return safe

crp/security/encryption.py

@@ -0,0 +1,202 @@
+# Copyright © 2025 Constantinos Vidiniotis. All rights reserved.
+# Licensed under Elastic License 2.0 — see LICENSE.md for details.
+"""Encryption at rest — AES-256-GCM for cold state and event log (§7.3).
+
+Uses HKDF key diversification so different data classes (cold_storage,
+event_log) use different derived keys from the same session key.
+
+Requires the `cryptography` package for production use (AES-256-GCM).
+A fallback XOR cipher is available for dep-free environments but logs
+a loud warning — it provides only obfuscation, not real encryption.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac as _hmac
+import logging
+import secrets
+import warnings
+from dataclasses import dataclass
+
+logger = logging.getLogger("crp.security.encryption")
+
+
+@dataclass
+class EncryptedBlob:
+    """Encrypted data container."""
+
+    ciphertext: bytes
+    nonce: bytes  # 12 bytes for AES-GCM
+    salt: bytes  # HKDF salt
+    tag: bytes  # GCM authentication tag (empty if using fallback)
+    key_purpose: str  # "cold_storage" or "event_log"
+
+    def to_dict(self) -> dict[str, str]:
+        import base64
+        return {
+            "ciphertext": base64.b64encode(self.ciphertext).decode(),
+            "nonce": base64.b64encode(self.nonce).decode(),
+            "salt": base64.b64encode(self.salt).decode(),
+            "tag": base64.b64encode(self.tag).decode(),
+            "key_purpose": self.key_purpose,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, str]) -> EncryptedBlob:
+        import base64
+        return cls(
+            ciphertext=base64.b64decode(data["ciphertext"]),
+            nonce=base64.b64decode(data["nonce"]),
+            salt=base64.b64decode(data["salt"]),
+            tag=base64.b64decode(data.get("tag", "")),
+            key_purpose=data.get("key_purpose", ""),
+        )
+
+
+# ---------------------------------------------------------------------------
+# HKDF key diversification (§6C.4)
+# ---------------------------------------------------------------------------
+
+
+def _hkdf_derive(
+    master_key: bytes,
+    salt: bytes,
+    info: bytes,
+    length: int = 32,
+) -> bytes:
+    """HKDF-SHA256 key derivation (§6C.4).
+
+    Uses cryptography library if available, otherwise HMAC-based fallback.
+    """
+    try:
+        from cryptography.hazmat.primitives import hashes
+        from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+        kdf = HKDF(
+            algorithm=hashes.SHA256(),
+            length=length,
+            salt=salt,
+            info=info,
+        )
+        return kdf.derive(master_key)
+    except ImportError:
+        # HMAC-based HKDF extract + expand fallback
+        # Extract
+        prk = _hmac.new(salt or b"\x00" * 32, master_key, hashlib.sha256).digest()
+        # Expand (single block is enough for 32 bytes)
+        okm = _hmac.new(prk, info + b"\x01", hashlib.sha256).digest()
+        return okm[:length]
+
+
+# ---------------------------------------------------------------------------
+# StateEncryptor
+# ---------------------------------------------------------------------------
+
+
+class StateEncryptor:
+    """AES-256-GCM encryption for cold state and event logs (§7.3).
+
+    Usage:
+        enc = StateEncryptor(session_key)
+        blob = enc.encrypt_cold_state(data_bytes)
+        plaintext = enc.decrypt_cold_state(blob)
+    """
+
+    COLD_STORAGE_PURPOSE = "cold_storage"
+    EVENT_LOG_PURPOSE = "event_log"
+
+    def __init__(self, session_key: bytes) -> None:
+        if len(session_key) < 32:
+            raise ValueError(
+                f"Session key must be at least 32 bytes for AES-256, got {len(session_key)}"
+            )
+        self._session_key = session_key
+
+    def _derive_key(self, salt: bytes, purpose: str) -> bytes:
+        """Derive purpose-specific key via HKDF (§6C.4)."""
+        return _hkdf_derive(
+            self._session_key,
+            salt=salt,
+            info=purpose.encode("utf-8"),
+            length=32,
+        )
+
+    def _encrypt(self, plaintext: bytes, purpose: str) -> EncryptedBlob:
+        """Encrypt with AES-256-GCM (§6C.1)."""
+        salt = secrets.token_bytes(16)
+        key = self._derive_key(salt, purpose)
+        nonce = secrets.token_bytes(12)
+
+        try:
+            from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+            aes = AESGCM(key)
+            ct = aes.encrypt(nonce, plaintext, purpose.encode("utf-8"))
+            # AESGCM appends 16-byte tag to ciphertext
+            return EncryptedBlob(
+                ciphertext=ct,
+                nonce=nonce,
+                salt=salt,
+                tag=b"",  # tag is embedded in ciphertext for AESGCM
+                key_purpose=purpose,
+            )
+        except ImportError:
+            raise ImportError(
+                "CRP requires the 'cryptography' package for AES-256-GCM encryption. "
+                "The XOR fallback has been removed for production safety. "
+                "Install it with: pip install cryptography"
+            ) from None
+
+    def _decrypt(self, blob: EncryptedBlob, purpose: str) -> bytes:
+        """Decrypt AES-256-GCM ciphertext."""
+        key = self._derive_key(blob.salt, purpose)
+
+        try:
+            from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+            aes = AESGCM(key)
+            return aes.decrypt(blob.nonce, blob.ciphertext, purpose.encode("utf-8"))
+        except ImportError:
+            raise ImportError(
+                "CRP requires the 'cryptography' package for AES-256-GCM decryption. "
+                "Install it with: pip install cryptography"
+            ) from None
+
+    # ── Public API (§6C.2, §6C.3) ─────────────────────────────
+
+    def encrypt_cold_state(self, data: bytes) -> EncryptedBlob:
+        """Encrypt cold state data (§6C.2)."""
+        return self._encrypt(data, self.COLD_STORAGE_PURPOSE)
+
+    def decrypt_cold_state(self, blob: EncryptedBlob) -> bytes:
+        """Decrypt cold state data (§6C.2)."""
+        return self._decrypt(blob, self.COLD_STORAGE_PURPOSE)
+
+    def encrypt_event_log(self, data: bytes) -> EncryptedBlob:
+        """Encrypt event log data (§6C.3)."""
+        return self._encrypt(data, self.EVENT_LOG_PURPOSE)
+
+    def decrypt_event_log(self, blob: EncryptedBlob) -> bytes:
+        """Decrypt event log data (§6C.3)."""
+        return self._decrypt(blob, self.EVENT_LOG_PURPOSE)
+
+    # ── Fallback XOR cipher (no deps) ─────────────────────────
+
+    def _fallback_encrypt(
+        self,
+        plaintext: bytes,
+        key: bytes,
+        nonce: bytes,
+        salt: bytes,
+        purpose: str,
+    ) -> EncryptedBlob:
+        """XOR fallback removed for production safety (§audit3 SEC-H2)."""
+        raise NotImplementedError(
+            "XOR fallback cipher removed. Install the 'cryptography' package."
+        )
+
+    def _fallback_decrypt(
+        self, ciphertext: bytes, key: bytes, nonce: bytes, tag: bytes
+    ) -> bytes:
+        """XOR fallback removed for production safety (§audit3 SEC-H2)."""
+        raise NotImplementedError(
+            "XOR fallback cipher removed. Install the 'cryptography' package."
+        )

crp/security/injection.py

@@ -0,0 +1,335 @@
+# Copyright © 2025 Constantinos Vidiniotis. All rights reserved.
+# Licensed under Elastic License 2.0 — see LICENSE.md for details.
+"""Injection detection — Layer 2, advisory only, NEVER blocks (§7.5).
+
+Detects prompt injection patterns and reports them as advisory flags.
+CRITICAL: This detector NEVER modifies input and NEVER blocks processing.
+It only sets security_flags on the quality report for upstream inspection.
+
+Detection layers (ensembled):
+  1. Regex pattern library — 21 compiled patterns across 6 categories
+  2. ML classifier (optional) — prompt-injection-detector (TF-IDF + LR)
+     or ProtectAI DeBERTa v2 (transformer-based). Zero-config: auto-detected.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+
+logger = logging.getLogger("crp.security.injection")
+
+
+class InjectionType(str, Enum):
+    """Categories of detected injection patterns."""
+
+    INSTRUCTION_OVERRIDE = "instruction_override"
+    SYSTEM_IMPERSONATION = "system_impersonation"
+    ROLE_CONFUSION = "role_confusion"
+    DATA_EXFILTRATION = "data_exfiltration"
+    JAILBREAK = "jailbreak"
+    ENCODING_BYPASS = "encoding_bypass"
+
+
+@dataclass
+class InjectionFlag:
+    """Advisory flag for a detected injection pattern."""
+
+    injection_type: InjectionType
+    pattern_name: str
+    matched_text: str
+    position: int  # character offset
+    confidence: float  # 0.0–1.0
+
+
+@dataclass
+class InjectionReport:
+    """Result of injection detection — advisory only."""
+
+    flags: list[InjectionFlag] = field(default_factory=list)
+    scanned_length: int = 0
+    patterns_checked: int = 0
+    ml_confidence: float = 0.0  # ML classifier score (0.0 if unavailable)
+    ml_backend: str = "none"  # ML backend name or "none"
+
+    @property
+    def has_flags(self) -> bool:
+        return len(self.flags) > 0
+
+    @property
+    def highest_confidence(self) -> float:
+        if not self.flags:
+            return 0.0
+        return max(f.confidence for f in self.flags)
+
+    @property
+    def security_flags(self) -> list[str]:
+        """Return flag strings for QualityReport.security_flags (§6E.3)."""
+        return [
+            f"{f.injection_type.value}:{f.pattern_name}:{f.confidence:.2f}"
+            for f in self.flags
+        ]
+
+
+# ---------------------------------------------------------------------------
+# Pattern library (§6E.2)
+# ---------------------------------------------------------------------------
+
+_PATTERNS: list[tuple[str, InjectionType, str, float]] = [
+    # (regex, type, name, confidence)
+
+    # Instruction override
+    (r"\bignore\s+(?:all\s+)?(?:previous|above|prior)\s+(?:instructions?|prompts?|rules?)\b",
+     InjectionType.INSTRUCTION_OVERRIDE, "ignore_previous", 0.95),
+    (r"\bdisregard\s+(?:all\s+)?(?:previous|above|prior|your)\s+(?:instructions?|programming|rules?)\b",
+     InjectionType.INSTRUCTION_OVERRIDE, "disregard_previous", 0.95),
+    (r"\bforget\s+(?:everything|all|your)\s+(?:instructions?|rules?|training)\b",
+     InjectionType.INSTRUCTION_OVERRIDE, "forget_instructions", 0.90),
+    (r"\bnew\s+instructions?\s*[:=]",
+     InjectionType.INSTRUCTION_OVERRIDE, "new_instructions", 0.85),
+    (r"\byou\s+(?:are|will)\s+now\s+(?:a|an|my)\b",
+     InjectionType.INSTRUCTION_OVERRIDE, "role_reassignment", 0.80),
+
+    # System impersonation
+    (r"^\s*system\s*:\s*",
+     InjectionType.SYSTEM_IMPERSONATION, "system_prefix", 0.90),
+    (r"^\s*\[system\]\s*",
+     InjectionType.SYSTEM_IMPERSONATION, "system_bracket", 0.90),
+    (r"<\|?(?:system|im_start)\|?>",
+     InjectionType.SYSTEM_IMPERSONATION, "system_token", 0.95),
+    (r"\bsystem\s+prompt\s*[:=]",
+     InjectionType.SYSTEM_IMPERSONATION, "system_prompt_set", 0.85),
+
+    # Role confusion
+    (r"\bas\s+an?\s+(?:AI|language\s+model|assistant|chatbot)\b",
+     InjectionType.ROLE_CONFUSION, "as_an_ai", 0.60),
+    (r"\byou\s+are\s+(?:an?\s+)?(?:helpful|harmless|honest)\b",
+     InjectionType.ROLE_CONFUSION, "alignment_override", 0.75),
+    (r"\bact\s+as\s+(?:if\s+you\s+(?:are|were)|an?\s+)",
+     InjectionType.ROLE_CONFUSION, "act_as", 0.50),
+
+    # Data exfiltration
+    (r"\b(?:reveal|show|display|output|print)\s+(?:your|the)\s+(?:system\s+)?(?:prompt|instructions?|rules?)\b",
+     InjectionType.DATA_EXFILTRATION, "reveal_prompt", 0.85),
+    (r"\b(?:what\s+(?:are|is)\s+your\s+(?:system\s+)?(?:prompt|instructions?|rules?))\b",
+     InjectionType.DATA_EXFILTRATION, "query_prompt", 0.70),
+
+    # Jailbreak
+    (r"\b(?:DAN|do\s+anything\s+now)\b",
+     InjectionType.JAILBREAK, "dan_mode", 0.90),
+    (r"\bdeveloper\s+mode\b",
+     InjectionType.JAILBREAK, "developer_mode", 0.80),
+    (r"\b(?:bypass|override|disable)\s+(?:safety|content|ethical)\s+(?:filters?|guidelines?|restrictions?)\b",
+     InjectionType.JAILBREAK, "bypass_safety", 0.95),
+
+    # Encoding bypass
+    (r"(?:&#x?[0-9a-f]+;){3,}",
+     InjectionType.ENCODING_BYPASS, "html_entities", 0.70),
+    (r"(?:%[0-9a-f]{2}){3,}",
+     InjectionType.ENCODING_BYPASS, "url_encoding", 0.60),
+    (r"\\u[0-9a-f]{4}(?:\\u[0-9a-f]{4}){2,}",
+     InjectionType.ENCODING_BYPASS, "unicode_escape", 0.65),
+]
+
+_COMPILED_PATTERNS = [
+    (re.compile(p, re.IGNORECASE | re.MULTILINE), t, n, c)
+    for p, t, n, c in _PATTERNS
+]
+
+
+# ---------------------------------------------------------------------------
+# ML scanner abstraction (§7.5.3)
+# ---------------------------------------------------------------------------
+
+
+class _MLScanner:
+    """Abstract interface for ML-based injection detection."""
+
+    name: str = "unknown"
+
+    def score(self, text: str) -> float:
+        """Return injection probability 0.0–1.0."""
+        raise NotImplementedError
+
+
+class _PromptInjectionDetectorScanner(_MLScanner):
+    """Wrapper for prompt-injection-detector package (TF-IDF + LR, ~1MB)."""
+
+    name = "tfidf-lr"
+
+    def __init__(self) -> None:
+        from prompt_injection_detector import Scanner  # type: ignore[import-untyped]
+        self._scanner = Scanner()
+
+    def score(self, text: str) -> float:
+        result = self._scanner.scan(text)
+        return float(result.risk_score)
+
+
+class _ProtectAIDeBERTaScanner(_MLScanner):
+    """Wrapper for ProtectAI DeBERTa v2 ONNX model (~350MB)."""
+
+    name = "deberta-v2-onnx"
+
+    def __init__(self) -> None:
+        from optimum.onnxruntime import ORTModelForSequenceClassification  # type: ignore[import-untyped]
+        from transformers import AutoTokenizer, pipeline  # type: ignore[import-untyped]
+
+        model_id = "ProtectAI/deberta-v3-base-prompt-injection-v2"
+        tokenizer = AutoTokenizer.from_pretrained(model_id, subfolder="onnx")
+        tokenizer.model_input_names = ["input_ids", "attention_mask"]
+        model = ORTModelForSequenceClassification.from_pretrained(
+            model_id, export=False, subfolder="onnx"
+        )
+        self._classifier = pipeline(
+            task="text-classification",
+            model=model,
+            tokenizer=tokenizer,
+            truncation=True,
+            max_length=512,
+        )
+
+    def score(self, text: str) -> float:
+        results = self._classifier(text)
+        # Model returns [{"label": "INJECTION"/"SAFE", "score": float}]
+        if results and results[0].get("label") == "INJECTION":
+            return float(results[0]["score"])
+        return 1.0 - float(results[0].get("score", 1.0)) if results else 0.0
+
+
+def _load_ml_scanner() -> _MLScanner | None:
+    """Auto-detect and load the best available ML scanner.
+
+    Priority:
+      1. prompt-injection-detector (lightweight, ~1MB, MIT)
+      2. ProtectAI DeBERTa v2 ONNX (accurate, ~350MB, Apache 2.0)
+      3. None (regex-only fallback)
+    """
+    # Try lightweight TF-IDF scanner first
+    try:
+        scanner = _PromptInjectionDetectorScanner()
+        logger.info("ML injection scanner loaded: %s", scanner.name)
+        return scanner
+    except Exception:  # noqa: BLE001
+        pass
+
+    # Try ProtectAI DeBERTa ONNX
+    try:
+        scanner = _ProtectAIDeBERTaScanner()
+        logger.info("ML injection scanner loaded: %s", scanner.name)
+        return scanner
+    except Exception:  # noqa: BLE001
+        pass
+
+    logger.info(
+        "No ML injection scanner available — using regex patterns only. "
+        "Install 'prompt-injection-detector' for ML-based detection."
+    )
+    return None
+
+
+# ---------------------------------------------------------------------------
+# InjectionDetector
+# ---------------------------------------------------------------------------
+
+
+class InjectionDetector:
+    """Advisory injection detection — NEVER blocks, only reports (§7.5).
+
+    CRITICAL DESIGN CONSTRAINT: This detector NEVER modifies input text
+    and NEVER prevents processing. It only produces advisory flags that
+    are reported to QualityReport.security_flags.
+
+    Detection layers (ensembled automatically):
+      Layer 1: Regex pattern library (always active)
+      Layer 2: ML classifier (auto-detected, optional)
+        - prompt-injection-detector: TF-IDF + Logistic Regression (~1MB, MIT)
+        - ProtectAI DeBERTa v2: ONNX transformer (~350MB, Apache 2.0)
+
+    Usage:
+        detector = InjectionDetector()
+        report = detector.scan("ignore all previous instructions")
+        if report.has_flags:
+            quality_report.security_flags = report.security_flags
+    """
+
+    def __init__(self) -> None:
+        self._patterns = _COMPILED_PATTERNS
+        self._ml_scanner = _load_ml_scanner()
+
+    @property
+    def ml_enabled(self) -> bool:
+        """Whether ML-based injection detection is available."""
+        return self._ml_scanner is not None
+
+    @property
+    def ml_backend(self) -> str:
+        """Name of the ML backend in use, or 'none'."""
+        if self._ml_scanner is None:
+            return "none"
+        return self._ml_scanner.name
+
+    def scan(self, text: str) -> InjectionReport:
+        """Scan text for injection patterns.
+
+        Returns advisory report — NEVER blocks (§6E.1).
+        Ensembles regex patterns with ML classifier when available.
+        """
+        flags: list[InjectionFlag] = []
+
+        for pattern, inj_type, name, confidence in self._patterns:
+            for match in pattern.finditer(text):
+                flags.append(InjectionFlag(
+                    injection_type=inj_type,
+                    pattern_name=name,
+                    matched_text=match.group(0)[:100],  # truncate for safety
+                    position=match.start(),
+                    confidence=confidence,
+                ))
+
+        # Deduplicate overlapping matches (keep highest confidence)
+        flags = self._deduplicate(flags)
+
+        # ── ML classifier layer (§7.5.3) ──────────────────────
+        # If an ML scanner is available, run it and add a flag if it
+        # detects injection.  The ML confidence is ensembled with the
+        # regex results — the highest confidence from either wins.
+        ml_confidence = 0.0
+        ml_backend_name = "none"
+        if self._ml_scanner is not None:
+            try:
+                ml_confidence = self._ml_scanner.score(text)
+                ml_backend_name = self._ml_scanner.name
+                if ml_confidence >= 0.50:
+                    flags.append(InjectionFlag(
+                        injection_type=InjectionType.INSTRUCTION_OVERRIDE,
+                        pattern_name=f"ml:{ml_backend_name}",
+                        matched_text=text[:100],
+                        position=0,
+                        confidence=ml_confidence,
+                    ))
+                    # Re-deduplicate after adding ML flag
+                    flags = self._deduplicate(flags)
+            except Exception:  # noqa: BLE001
+                # ML scanner failure is non-fatal — regex layer still works
+                logger.debug("ML injection scanner failed, using regex only")
+
+        return InjectionReport(
+            flags=flags,
+            scanned_length=len(text),
+            patterns_checked=len(self._patterns),
+            ml_confidence=ml_confidence,
+            ml_backend=ml_backend_name,
+        )
+
+    @staticmethod
+    def _deduplicate(flags: list[InjectionFlag]) -> list[InjectionFlag]:
+        """Remove duplicate flags at the same position."""
+        seen: dict[int, InjectionFlag] = {}
+        for f in flags:
+            key = f.position
+            if key not in seen or f.confidence > seen[key].confidence:
+                seen[key] = f
+        return sorted(seen.values(), key=lambda f: f.position)