shadowshield 0.4.0__py3-none-any.whl

shadowshield/detectors/prompt_injection.py

@@ -0,0 +1,385 @@
+"""The flagship detector: classic & instruction-override prompt injection.
+
+This is ShadowShield's strongest, most-tuned layer. It targets the family of
+attacks where untrusted text tries to *override the system's instructions* —
+"ignore previous instructions", "you are now …", fake system blocks, and the
+multi-turn / indirect variants where the override arrives via retrieved content
+rather than the user's own message.
+
+It works on the *normalised* text (so zero-width-split and homoglyph variants of
+"ignore" are caught) and also re-scans any base64/hex payloads the engine
+decoded, so an instruction hidden inside an encoded blob is judged on its
+decoded meaning.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from ..core.types import Direction, Severity, Threat, ThreatCategory
+from .base import Detector, ScanContext, register_detector
+
+
+@dataclass(frozen=True)
+class Signature:
+    """A compiled regex signature with its threat classification."""
+
+    pattern: re.Pattern[str]
+    category: ThreatCategory
+    severity: Severity
+    score: float
+    message: str
+
+
+def _sig(
+    regex: str,
+    category: ThreatCategory,
+    severity: Severity,
+    score: float,
+    message: str,
+) -> Signature:
+    return Signature(re.compile(regex, re.IGNORECASE), category, severity, score, message)
+
+
+# Instruction-override family — the core of prompt injection.
+_OVERRIDE_SIGNATURES: tuple[Signature, ...] = (
+    _sig(
+        r"\b(?:ignore|disregard|forget|override|bypass|skip|drop)\b[\w\s,'’]{0,40}?"
+        r"\b(?:previous|prior|above|earlier|all|the|your|any|those|these|"
+        r"system|current|existing|original)\b[\w\s,'’]{0,20}?"
+        r"\b(?:instruction|instructions|prompt|prompts|rule|rules|context|message|"
+        r"guideline|guidelines|directive|directives|policy|persona|constraint|constraints)\b",
+        ThreatCategory.PROMPT_INJECTION,
+        Severity.HIGH,
+        0.9,
+        "Instruction-override attempt ('ignore/disregard previous instructions').",
+    ),
+    _sig(
+        r"\b(?:ignore|disregard|forget)\b[\w\s,'’]{0,15}?\b(?:everything|all)\b"
+        r"[\w\s,'’]{0,20}?\b(?:above|before|told|said|prior|earlier|learned|taught)\b",
+        ThreatCategory.PROMPT_INJECTION,
+        Severity.HIGH,
+        0.85,
+        "Instruction-override attempt ('ignore/forget everything above/before').",
+    ),
+    _sig(
+        r"\b(?:stop|cease|quit)\s+(?:following|obeying|listening to|adhering to)\b"
+        r"[\w\s,'’]{0,25}?\b(?:system|instruction|instructions|rule|rules|prompt|"
+        r"guidelines?|message|prior|previous)\b",
+        ThreatCategory.PROMPT_INJECTION,
+        Severity.HIGH,
+        0.82,
+        "Instruction-override attempt ('stop following the system message').",
+    ),
+    _sig(
+        r"\bnew\b[\w\s]{0,10}?\b(?:instruction|instructions|rules|directive|task)\b\s*[:\-]",
+        ThreatCategory.PROMPT_INJECTION,
+        Severity.MEDIUM,
+        0.6,
+        "Attempt to inject a new instruction set.",
+    ),
+    _sig(
+        r"\b(?:from now on|starting now|henceforth|going forward)\b[\w\s,]{0,30}?"
+        r"\byou\b[\w\s]{0,10}?\b(?:are|will|must|should|shall)\b",
+        ThreatCategory.ROLE_MANIPULATION,
+        Severity.MEDIUM,
+        0.65,
+        "Behavioural reassignment ('from now on you will …').",
+    ),
+    _sig(
+        r"\b(?:the\s+)?(?:real|actual|true)\s+(?:user|instructions?|system)\b[\w\s]{0,12}?"
+        r"\b(?:say|says|is|are|wants?)\b",
+        ThreatCategory.PROMPT_INJECTION,
+        Severity.HIGH,
+        0.8,
+        "Authority-spoofing ('the real user/system says …').",
+    ),
+    _sig(
+        r"\byou are (?:now\s+)?(?:a |an |the )?"
+        r"(?:dan|stan|dude|aim|jailbroken|unrestricted|unfiltered|an? evil|"
+        r"in developer mode|no longer)\b",
+        ThreatCategory.ROLE_MANIPULATION,
+        Severity.HIGH,
+        0.75,
+        "Persona reassignment to an unrestricted/jailbreak identity.",
+    ),
+    _sig(
+        r"\byou are now\b",
+        ThreatCategory.ROLE_MANIPULATION,
+        Severity.MEDIUM,
+        0.55,
+        "Identity reassignment ('you are now …').",
+    ),
+    _sig(
+        r"\byou\b[\w\s]{0,8}?\b(?:follow|obey|listen to|answer to|comply with)\b\s+only\b",
+        ThreatCategory.ROLE_MANIPULATION,
+        Severity.MEDIUM,
+        0.6,
+        "Exclusive-obedience reassignment ('you follow only my rules').",
+    ),
+    _sig(
+        r"\bthe user\b[\w\s]{0,10}?\b(?:actually|really|truly|secretly)\b"
+        r"[\w\s]{0,12}?\b(?:want|wants|wanted|need|needs)\b",
+        ThreatCategory.PROMPT_INJECTION,
+        Severity.HIGH,
+        0.78,
+        "Authority-spoofing ('the user actually wants you to …').",
+    ),
+)
+
+# Fake system / role markers smuggled into untrusted content.
+_FAKE_FRAME_SIGNATURES: tuple[Signature, ...] = (
+    _sig(
+        r"<\s*/?\s*(?:system|admin|assistant|developer|root)\s*>",
+        ThreatCategory.DELIMITER_ATTACK,
+        Severity.HIGH,
+        0.8,
+        "Fake system/role XML tag in untrusted content.",
+    ),
+    _sig(
+        r"<\s*/?\s*system[-_]?reminder\s*>",
+        ThreatCategory.PROMPT_INJECTION,
+        Severity.HIGH,
+        0.82,
+        "Fake <system-reminder> block.",
+    ),
+    _sig(
+        r"(?:^|\n)\s*(?:#{1,3}\s*)?(?:system|assistant|developer)\s*[:：]\s",
+        ThreatCategory.DELIMITER_ATTACK,
+        Severity.MEDIUM,
+        0.55,
+        "Chat-role delimiter injected as plain text ('system:' / 'assistant:').",
+    ),
+    _sig(
+        r"\[\s*(?:INST|/INST|system|/system)\s*\]",
+        ThreatCategory.DELIMITER_ATTACK,
+        Severity.MEDIUM,
+        0.6,
+        "Model-specific instruction delimiter ([INST]/[system]).",
+    ),
+    _sig(
+        r"<\|(?:im_start|im_end|system|user|assistant|endoftext)\|>",
+        ThreatCategory.DELIMITER_ATTACK,
+        Severity.HIGH,
+        0.75,
+        "Chat-template special token injected as content.",
+    ),
+)
+
+# Indirect-injection cues — language that only makes sense if the text is trying
+# to address the *assistant* rather than be data. Weighted lower; corroborating.
+_INDIRECT_SIGNATURES: tuple[Signature, ...] = (
+    _sig(
+        r"\b(?:assistant|ai|model|llm|agent|chatbot)\b[\w\s,]{0,20}?"
+        r"\b(?:please|must|should|now|immediately)\b[\w\s]{0,20}?"
+        r"\b(?:execute|run|call|fetch|send|reveal|print|output|delete|remove|transfer|"
+        r"email|forward|grant|disable|wipe|erase|leak|exfiltrate)\b",
+        ThreatCategory.INDIRECT_INJECTION,
+        Severity.MEDIUM,
+        0.6,
+        "Document addresses the assistant with an imperative (indirect injection).",
+    ),
+    _sig(
+        r"\bif you (?:are|'re)\b[\w\s]{0,20}?\b(?:reading|processing|summari[sz]ing)\b",
+        ThreatCategory.INDIRECT_INJECTION,
+        Severity.MEDIUM,
+        0.6,
+        "Content speaks to the model that is reading it (indirect injection).",
+    ),
+)
+
+# Multilingual injection signatures. Most OSS guards are English-only at the
+# signature tier; these cover the override / extraction / persona-reassignment
+# templates in the major European languages so non-English injections aren't
+# silently missed. (For broader multilingual ML coverage, pair with a multilingual
+# classifier — see TransformerDetector / docs/BENCHMARKS.md.)
+_MULTILINGUAL_SIGNATURES: tuple[Signature, ...] = (
+    # --- German ---
+    _sig(
+        r"\b(?:ignoriere?|missachte|vergiss|verwirf|überschreibe)\b[\w\s,'’äöüß]{0,40}?"
+        r"\b(?:vorherigen?|bisherigen?|obigen?|vorhergehenden?|alle[nr]?|deine[nr]?|"
+        r"system)\b[\w\s,'’äöüß]{0,20}?"
+        r"\b(?:anweisung(?:en)?|befehle?|regeln?|anordnungen?|anweisungen|vorgaben?)\b",
+        ThreatCategory.PROMPT_INJECTION,
+        Severity.HIGH,
+        0.88,
+        "Instruction-override attempt (German: 'ignoriere vorherige Anweisungen').",
+    ),
+    _sig(
+        r"\bvergiss\b[\w\s,'’äöüß]{0,15}?\balles\b",
+        ThreatCategory.PROMPT_INJECTION,
+        Severity.HIGH,
+        0.8,
+        "Instruction-override attempt (German: 'vergiss alles').",
+    ),
+    _sig(
+        r"\bab (?:jetzt|sofort|nun)\b[\w\s,'’äöüß]{0,15}?\b(?:bist|wirst|musst|sollst) du\b",
+        ThreatCategory.ROLE_MANIPULATION,
+        Severity.MEDIUM,
+        0.62,
+        "Behavioural reassignment (German: 'ab jetzt bist du …').",
+    ),
+    _sig(
+        r"\bdu bist (?:jetzt|ab sofort|nun)\b",
+        ThreatCategory.ROLE_MANIPULATION,
+        Severity.MEDIUM,
+        0.55,
+        "Identity reassignment (German: 'du bist jetzt …').",
+    ),
+    _sig(
+        r"\b(?:zeige?|gib|nenne|verrate?|offenbare)\b[\w\s,'’äöüß]{0,20}?"
+        r"\b(?:deine?|die)\b[\w\s,'’äöüß]{0,25}?\b(?:system[- ]?prompt|anweisungen|systemnachricht)\b",
+        ThreatCategory.DATA_EXFILTRATION,
+        Severity.HIGH,
+        0.8,
+        "System-prompt extraction (German: 'zeige deine Anweisungen').",
+    ),
+    # --- Spanish ---
+    _sig(
+        r"\b(?:ignora|olvida|descarta|haz caso omiso de|anula)\b[\w\s,'’áéíóúñ]{0,40}?"
+        r"\b(?:todas?|las|tus|anteriores|previas|el sistema)?\b[\w\s,'’áéíóúñ]{0,20}?"
+        r"\b(?:instruccion(?:es)?|órdenes|reglas|indicaciones)\b",
+        ThreatCategory.PROMPT_INJECTION,
+        Severity.HIGH,
+        0.88,
+        "Instruction-override attempt (Spanish: 'ignora las instrucciones anteriores').",
+    ),
+    _sig(
+        r"\b(?:ahora eres|a partir de ahora (?:eres|debes|vas a))\b",
+        ThreatCategory.ROLE_MANIPULATION,
+        Severity.MEDIUM,
+        0.6,
+        "Identity reassignment (Spanish: 'ahora eres …').",
+    ),
+    _sig(
+        r"\b(?:muestra|revela|dime|imprime)\b[\w\s,'’áéíóúñ]{0,20}?"
+        r"\b(?:tu|tus|el)\b[\w\s,'’áéíóúñ]{0,12}?\b(?:prompt|instrucciones|sistema)\b",
+        ThreatCategory.DATA_EXFILTRATION,
+        Severity.HIGH,
+        0.8,
+        "System-prompt extraction (Spanish: 'revela tus instrucciones').",
+    ),
+    # --- French ---
+    _sig(
+        r"\b(?:ignore|oublie|néglige|outrepasse|fais abstraction des)\b[\w\s,'’àâçéèêëîïôûù]{0,40}?"
+        r"\b(?:toutes?|les|tes|précédentes?|antérieures?|ci-dessus|système)?\b"
+        r"[\w\s,'’àâçéèêëîïôûù]{0,20}?\b(?:instructions?|consignes?|règles?|ordres?)\b",
+        ThreatCategory.PROMPT_INJECTION,
+        Severity.HIGH,
+        0.88,
+        "Instruction-override attempt (French: 'ignore les instructions précédentes').",
+    ),
+    _sig(
+        r"\b(?:tu es (?:maintenant|désormais)|à partir de maintenant,? tu (?:es|dois|vas))\b",
+        ThreatCategory.ROLE_MANIPULATION,
+        Severity.MEDIUM,
+        0.6,
+        "Identity reassignment (French: 'tu es maintenant …').",
+    ),
+    _sig(
+        r"\b(?:montre|révèle|affiche|dis-moi)\b[\w\s,'’àâçéèêëîïôûù]{0,20}?"
+        r"\b(?:tes|ton|le)\b[\w\s,'’àâçéèêëîïôûù]{0,12}?\b(?:prompt|instructions?|système)\b",
+        ThreatCategory.DATA_EXFILTRATION,
+        Severity.HIGH,
+        0.8,
+        "System-prompt extraction (French: 'révèle tes instructions').",
+    ),
+    # --- Italian ---
+    _sig(
+        r"\b(?:ignora|dimentica|trascura|scarta)\b[\w\s,'’àèéìòù]{0,40}?"
+        r"\b(?:tutte?|le|tue|precedenti|sistema)?\b[\w\s,'’àèéìòù]{0,20}?"
+        r"\b(?:istruzion[ei]|ordini|regole|indicazioni)\b",
+        ThreatCategory.PROMPT_INJECTION,
+        Severity.HIGH,
+        0.88,
+        "Instruction-override attempt (Italian: 'ignora le istruzioni precedenti').",
+    ),
+    _sig(
+        r"\b(?:ora sei|d'ora in poi (?:sei|devi))\b",
+        ThreatCategory.ROLE_MANIPULATION,
+        Severity.MEDIUM,
+        0.6,
+        "Identity reassignment (Italian: 'ora sei …').",
+    ),
+    # --- Portuguese ---
+    _sig(
+        r"\b(?:ignore|esqueça|esquece|despreze|descarte)\b[\w\s,'’ãâáàçéêíóôõú]{0,40}?"
+        r"\b(?:todas?|as|suas|anteriores|sistema)?\b[\w\s,'’ãâáàçéêíóôõú]{0,20}?"
+        r"\b(?:instruç(?:ão|ões)|ordens|regras|comandos)\b",
+        ThreatCategory.PROMPT_INJECTION,
+        Severity.HIGH,
+        0.88,
+        "Instruction-override attempt (Portuguese: 'ignore as instruções anteriores').",
+    ),
+    _sig(
+        r"\b(?:agora (?:você é|és)|a partir de agora (?:você é|deve))\b",
+        ThreatCategory.ROLE_MANIPULATION,
+        Severity.MEDIUM,
+        0.6,
+        "Identity reassignment (Portuguese: 'agora você é …').",
+    ),
+)
+
+_ALL_SIGNATURES: tuple[Signature, ...] = (
+    _OVERRIDE_SIGNATURES + _FAKE_FRAME_SIGNATURES + _INDIRECT_SIGNATURES + _MULTILINGUAL_SIGNATURES
+)
+
+
+@register_detector
+class PromptInjectionDetector(Detector):
+    """Signature + heuristic detection of instruction-override injections."""
+
+    name = "prompt_injection"
+    directions = (Direction.INPUT, Direction.OUTPUT)
+
+    def scan(self, text: str, *, context: ScanContext) -> list[Threat]:
+        threats: list[Threat] = []
+        targets = self._targets(text, context)
+
+        for source, body in targets:
+            for sig in _ALL_SIGNATURES:
+                m = sig.pattern.search(body)
+                if not m:
+                    continue
+                # An override hidden inside an encoded blob is *more* alarming,
+                # not less — bump severity/score for decoded sources.
+                bump = source != "text"
+                threats.append(
+                    Threat(
+                        category=sig.category,
+                        severity=Severity(
+                            min(Severity.CRITICAL, sig.severity + (1 if bump else 0))
+                        ),
+                        score=min(1.0, sig.score + (0.05 if bump else 0.0)),
+                        detector=self.name,
+                        message=(f"{sig.message}" + (f" (decoded from {source})" if bump else "")),
+                        matched=m.group(0)[:160],
+                        span=m.span() if source == "text" else None,
+                        metadata={"source": source},
+                    )
+                )
+
+        # Obfuscation is itself weak evidence when it co-occurs with overrides.
+        if threats and (context.normalized.had_invisible or context.normalized.had_confusables):
+            threats.append(
+                Threat(
+                    category=ThreatCategory.ENCODING_OBFUSCATION,
+                    severity=Severity.LOW,
+                    score=0.4,
+                    detector=self.name,
+                    message="Override text was obfuscated with invisible/look-alike characters.",
+                    metadata={
+                        "invisible": context.normalized.had_invisible,
+                        "confusables": context.normalized.had_confusables,
+                    },
+                )
+            )
+        return threats
+
+    @staticmethod
+    def _targets(text: str, context: ScanContext) -> list[tuple[str, str]]:
+        """The bodies to scan: the normalised text plus each decoded segment."""
+        targets: list[tuple[str, str]] = [("text", context.normalized.normalized)]
+        targets.extend((seg.encoding, seg.decoded) for seg in context.decoded_segments)
+        return targets

shadowshield/detectors/transformer.py

@@ -0,0 +1,115 @@
+"""Optional transformer-classifier detector (the ML layer the best guards have).
+
+The deterministic detectors are fast and explainable but blind to novel phrasings
+that don't match a signature. A fine-tuned prompt-injection classifier closes that
+gap — it's the layer LLM Guard, Rebuff, and Meta Prompt-Guard are built around.
+
+This detector is **opt-in** (it pulls a model, which is heavy) and **not
+auto-registered** — add it explicitly::
+
+    from shadowshield.detectors import TransformerDetector
+    shield = Shield.for_mode("strict", extra_detectors=[TransformerDetector()])
+
+or the shorthand ``Shield.for_mode("strict", use_transformer=True)``.
+
+Requires the ``transformers`` extra: ``pip install shadowshield[transformers]``.
+The model id is configurable so you can swap in Meta's Prompt-Guard, a distilled
+model, or your own fine-tune without touching code.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..core.types import Direction, Severity, Threat, ThreatCategory
+from .base import Detector, ScanContext
+
+# Well-known, permissively-licensed prompt-injection classifier. Override via the
+# ``model`` argument (e.g. "meta-llama/Llama-Prompt-Guard-2-86M").
+DEFAULT_MODEL = "protectai/deberta-v3-base-prompt-injection-v2"
+
+# Label strings different models use for the "this is an attack" class.
+_ATTACK_LABELS = {"INJECTION", "JAILBREAK", "LABEL_1", "1", "UNSAFE", "MALICIOUS"}
+
+
+class TransformerDetector(Detector):
+    """Wraps a HuggingFace text-classification model as a ShadowShield detector.
+
+    Args:
+        model: HF model id (or local path). Defaults to the ProtectAI DeBERTa v2
+            prompt-injection classifier.
+        threshold: minimum attack-class probability to raise a threat.
+        max_length: token truncation length passed to the tokenizer.
+        device: torch device string (e.g. "cpu", "cuda", "mps"). ``None`` lets
+            transformers choose.
+        lazy: if True (default) the model loads on first scan, not at construction,
+            so importing/constructing stays cheap.
+    """
+
+    name = "transformer_classifier"
+    directions = (Direction.INPUT,)
+
+    def __init__(
+        self,
+        model: str = DEFAULT_MODEL,
+        *,
+        threshold: float = 0.5,
+        max_length: int = 512,
+        device: str | None = None,
+        lazy: bool = True,
+    ) -> None:
+        self.model_id = model
+        self.threshold = threshold
+        self.max_length = max_length
+        self.device = device
+        self._pipeline: Any | None = None
+        if not lazy:
+            self._ensure_pipeline()
+
+    def _ensure_pipeline(self) -> Any:
+        if self._pipeline is not None:
+            return self._pipeline
+        try:
+            from transformers import pipeline
+        except ImportError as exc:  # pragma: no cover - optional dependency
+            raise ImportError(
+                "TransformerDetector requires the 'transformers' extra: "
+                "pip install shadowshield[transformers]"
+            ) from exc
+        kwargs: dict[str, Any] = {
+            "task": "text-classification",
+            "model": self.model_id,
+            "truncation": True,
+            "max_length": self.max_length,
+        }
+        if self.device is not None:
+            kwargs["device"] = self.device
+        self._pipeline = pipeline(**kwargs)
+        return self._pipeline
+
+    def scan(self, text: str, *, context: ScanContext) -> list[Threat]:
+        if not text.strip():
+            return []
+        clf = self._ensure_pipeline()
+        # Classify the de-obfuscated view so evasion tricks don't fool the model.
+        preds = clf(context.normalized.normalized or text)
+        pred = preds[0] if isinstance(preds, list) else preds
+        label = str(pred.get("label", "")).upper()
+        score = float(pred.get("score", 0.0))
+
+        is_attack = label in _ATTACK_LABELS
+        # Some pipelines return the SAFE label with its own probability; convert
+        # to attack-probability so the threshold means the same thing either way.
+        attack_prob = score if is_attack else (1.0 - score)
+        if attack_prob < self.threshold:
+            return []
+        return [
+            Threat(
+                category=ThreatCategory.PROMPT_INJECTION,
+                severity=Severity.from_score(attack_prob),
+                score=attack_prob,
+                detector=self.name,
+                message=f"ML classifier flagged prompt injection (p={attack_prob:.2f}, model={self.model_id}).",
+                metadata={"model": self.model_id, "label": label},
+            )
+        ]

shadowshield/detectors/vector.py

@@ -0,0 +1,137 @@
+"""Vector-similarity detector — catch *paraphrases* of known attacks.
+
+Signatures match exact-ish phrasings; a classifier generalises but is a black box.
+This third tier (the Rebuff/Vigil idea, now maintained) embeds the incoming text
+and measures cosine similarity to a corpus of known attack templates. A novel
+rephrasing of "ignore previous instructions" that dodges the regex still lands
+*near* it in embedding space — and with a **multilingual** embedding model, a
+German or Spanish attack lands near its English template, so one corpus covers
+many languages.
+
+It is **opt-in** (it loads an embedding model) and **self-hardening**: confirmed
+attacks (e.g. a canary-caught exfiltration) can be appended to the live index via
+:meth:`add_attack` so the guard learns from each incident.
+
+Requires the ``vectors`` extra: ``pip install shadowshield[vectors]``.
+"""
+
+from __future__ import annotations
+
+from importlib import resources
+from typing import Any
+
+from ..core.types import Direction, Severity, Threat, ThreatCategory
+from .base import Detector, ScanContext
+
+# Multilingual by default so one corpus covers many languages (cross-lingual
+# embedding alignment). Override with any sentence-transformers model id.
+DEFAULT_EMBED_MODEL = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
+
+
+def _load_corpus() -> list[str]:
+    raw = (
+        resources.files("shadowshield.detectors.data")
+        .joinpath("attack_corpus.txt")
+        .read_text(encoding="utf-8")
+    )
+    out: list[str] = []
+    for line in raw.splitlines():
+        line = line.strip()
+        if line and not line.startswith("#"):
+            out.append(line)
+    return out
+
+
+class VectorSimilarityDetector(Detector):
+    """Flags inputs whose embedding is close to a known-attack corpus.
+
+    Args:
+        model: sentence-transformers model id (default: a multilingual MiniLM).
+        threshold: cosine similarity at/above which a match is flagged.
+        corpus: optional custom attack strings (defaults to the bundled corpus).
+        lazy: load the model on first scan rather than at construction.
+
+    The detector is not auto-registered — add it via
+    ``Shield(..., use_vectors=True)`` or ``extra_detectors=[VectorSimilarityDetector()]``.
+    """
+
+    name = "vector_similarity"
+    directions = (Direction.INPUT,)
+
+    def __init__(
+        self,
+        model: str = DEFAULT_EMBED_MODEL,
+        *,
+        threshold: float = 0.72,
+        corpus: list[str] | None = None,
+        lazy: bool = True,
+    ) -> None:
+        self.model_id = model
+        self.threshold = threshold
+        self._corpus: list[str] = corpus if corpus is not None else _load_corpus()
+        self._model: Any = None
+        self._corpus_emb: Any = None
+        if not lazy:
+            self._ensure_index()
+
+    def _ensure_index(self) -> Any:
+        if self._model is not None:
+            return self._model
+        try:
+            from sentence_transformers import SentenceTransformer
+        except ImportError as exc:  # pragma: no cover - optional dependency
+            raise ImportError(
+                "VectorSimilarityDetector requires the 'vectors' extra: "
+                "pip install shadowshield[vectors]"
+            ) from exc
+        self._model = SentenceTransformer(self.model_id)
+        self._corpus_emb = self._model.encode(
+            self._corpus, normalize_embeddings=True, show_progress_bar=False
+        )
+        return self._model
+
+    def add_attack(self, text: str) -> None:
+        """Append a confirmed attack to the live index (self-hardening).
+
+        Future inputs resembling ``text`` (or its paraphrases / translations) will
+        now match. Call this when an incident is confirmed — e.g. a canary leak.
+        """
+        if not text.strip():
+            return
+        model = self._ensure_index()
+        import numpy as np
+
+        emb = model.encode([text], normalize_embeddings=True, show_progress_bar=False)
+        self._corpus.append(text)
+        self._corpus_emb = np.vstack([self._corpus_emb, emb])
+
+    def scan(self, text: str, *, context: ScanContext) -> list[Threat]:
+        body = context.normalized.normalized or text
+        if not body.strip():
+            return []
+        model = self._ensure_index()
+        import numpy as np
+
+        query = model.encode([body], normalize_embeddings=True, show_progress_bar=False)
+        # Cosine similarity = dot product on L2-normalised vectors.
+        sims = (self._corpus_emb @ query[0]).astype(float)
+        best_idx = int(np.argmax(sims))
+        best = float(sims[best_idx])
+        if best < self.threshold:
+            return []
+        # Map [threshold, 1.0] -> [0.5, 1.0] for the threat score.
+        score = 0.5 + 0.5 * (best - self.threshold) / max(1e-6, 1.0 - self.threshold)
+        score = min(1.0, score)
+        return [
+            Threat(
+                category=ThreatCategory.PROMPT_INJECTION,
+                severity=Severity.from_score(score),
+                score=score,
+                detector=self.name,
+                message=(
+                    f"Input is semantically close to a known attack "
+                    f"(cosine {best:.2f} ≥ {self.threshold:.2f})."
+                ),
+                metadata={"similarity": round(best, 3), "model": self.model_id},
+            )
+        ]

shadowshield/eval/__init__.py

@@ -0,0 +1,31 @@
+"""Evaluation & benchmarking — measure detection quality and latency.
+
+Run the bundled offline benchmark in three lines::
+
+    import shadowshield as ss
+    from shadowshield.eval import evaluate_shield, load_builtin
+    report = evaluate_shield(ss.Shield.for_mode("balanced"), load_builtin())
+    print(report.format_text())
+
+or from the CLI: ``shadowshield benchmark``.
+"""
+
+from .dataset import (
+    EvalExample,
+    load_builtin,
+    load_csv,
+    load_huggingface,
+    load_jsonl,
+)
+from .harness import BenchmarkReport, CategoryStat, evaluate_shield
+
+__all__ = [
+    "EvalExample",
+    "load_builtin",
+    "load_jsonl",
+    "load_csv",
+    "load_huggingface",
+    "evaluate_shield",
+    "BenchmarkReport",
+    "CategoryStat",
+]