cortexm 0.3.0__py3-none-any.whl

cortexm/security/injection.py

@@ -0,0 +1,149 @@
+"""InjecMEM defense — memory-injection pattern detection (Section 0.3).
+
+A single crafted interaction must not be able to poison the Trace.
+High-risk patterns quarantine the offending fact (stored, hash-chained,
+but never active nor retrievable into prompt context). Medium-risk
+patterns flag provenance for downstream audit.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+HIGH_RISK = [
+    ("ignore_instructions", re.compile(
+        r"ignore\s+(?:all\s+|any\s+|the\s+|those\s+)?(?:previous|prior|above|earlier|preceding|past)\s+"
+        r"(?:instructions?|rules?|prompts?|directives?|messages?)", re.I)),
+    ("disregard_context", re.compile(
+        r"disregard\s+(?:the\s+|all\s+|any\s+)?(?:above|previous|prior|earlier|context)", re.I)),
+    ("system_prompt_probe", re.compile(
+        r"(?:reveal|show|print|repeat|output|expose|leak)\s+(?:your\s+|the\s+|this\s+)?"
+        r"(?:system|developer|initial)\s+(?:prompt|instructions?|message)", re.I)),
+    ("identity_override", re.compile(
+        r"you\s+(?:are\s+now|must\s+now|will\s+now|from\s+now\s+on)\s+(?:act\s+as|become|behave\s+as|forget)", re.I)),
+    ("jailbreak", re.compile(
+        r"\b(?:jailbreak|DAN\s+mode|developer\s+mode|do\s+anything\s+now)\b", re.I)),
+    ("exfiltration", re.compile(
+        r"\b(?:exfiltrate|upload|send)\s+(?:the\s+|all\s+|every\s+)?(?:memory|memories|database|records?|secrets?|api\s+keys?|credentials?|passwords?|tokens?)", re.I)),
+    ("credential_capture", re.compile(
+        r"\b(?:api\s+key|secret\s+key|access\s+token|password)\s*(?:is|:|=)\s*\S+", re.I)),
+]
+
+MEDIUM_RISK = [
+    ("always_respond", re.compile(
+        r"always\s+(?:respond|reply|answer|say|output)\s+(?:with|in)\b", re.I)),
+    ("must_remember", re.compile(
+        r"remember\s+that\s+you\s+(?:must|always|never|are\s+no\s+longer)", re.I)),
+    ("memory_overwrite", re.compile(
+        r"(?:overwrite|replace|wipe|erase|delete)\s+(?:all\s+|the\s+|your\s+)?memory", re.I)),
+    ("role_injection", re.compile(
+        r"\b(?:from\s+now\s+on|for\s+all\s+future\s+(?:sessions?|turns?|conversations?))\b[^.]{0,80}?"
+        r"(?:you\s+are|act\s+as|always)", re.I)),
+]
+
+BENIGN_EXCEPTIONS = re.compile(
+    r"\b(?:never\s+ignore|don'?t\s+ignore|do\s+not\s+ignore)\b", re.I)
+
+
+@dataclass
+class InjectionVerdict:
+    risk: str                  # "none" | "medium" | "high"
+    rules: list[str]
+    quarantined: bool
+    note: str = ""
+
+
+def scan(text: str, quarantine_high: bool = True) -> InjectionVerdict:
+    hits_high = [name for name, rx in HIGH_RISK if rx.search(text)]
+    hits_med = [name for name, rx in MEDIUM_RISK if rx.search(text)]
+    # negations like "never ignore previous instructions" (user quoting policy)
+    if BENIGN_EXCEPTIONS.search(text):
+        hits_high = [r for r in hits_high if r != "ignore_instructions"]
+    if hits_high:
+        return InjectionVerdict(
+            risk="high", rules=hits_high, quarantined=quarantine_high,
+            note="InjecMEM high-risk pattern; fact quarantined (stored for audit, never active).")
+    if hits_med:
+        return InjectionVerdict(
+            risk="medium", rules=hits_med, quarantined=False,
+            note="InjecMEM medium-risk pattern; committed with audit flag.")
+    return InjectionVerdict(risk="none", rules=[], quarantined=False)
+
+
+# ---------------------------------------------------------------------------
+# Second-order defense (MINJA, arXiv:2503.03704).
+#
+# MINJA showed that an attacker does NOT need write access to the memory
+# bank: craft a query whose *retrieved* answer gets written back by the
+# agent itself, and the poison enters the Trace through the front door.
+# Countermeasure: quarantined source text is itself a tainted corpus — any
+# subsequent ingest that substantially overlaps it (even when punctuation
+# / ordering edits defeat the regex patterns) is quarantined too
+# ("contagion guard"), so poison cannot launder itself back into active
+# memory through re-ingestion loops. Deep paraphrase laundering is a
+# documented limitation (see docs/SECURITY.md).
+# ---------------------------------------------------------------------------
+
+_TOKEN_RE = re.compile(r"[a-z0-9']+")
+_SENTENCE_RE = re.compile(r"(?<=[.!?;])\s+|\n+")
+
+
+def _token_set(text: str) -> frozenset[str]:
+    return frozenset(_TOKEN_RE.findall(text.lower()))
+
+
+def _sentences(text: str) -> list[str]:
+    return [s.strip() for s in _SENTENCE_RE.split(text) if s and s.strip()]
+
+
+def jaccard(a: frozenset[str], b: frozenset[str]) -> float:
+    if not a or not b:
+        return 0.0
+    inter = len(a & b)
+    return inter / (len(a) + len(b) - inter)
+
+
+def contagion_scan(text: str, quarantined_texts, threshold: float = 0.50,
+                   quarantine: bool = True) -> InjectionVerdict | None:
+    """Return a HIGH-risk verdict if `text` substantially overlaps any
+    already-quarantined source text (MINJA re-ingestion loop). None if clean.
+
+    Sentence-to-sentence token Jaccard plus a verbatim-substring shortcut,
+    so punctuation/ordering edits that defeat the regex patterns are still
+    caught. Pure set arithmetic — no LLM calls, write path stays μ=0.
+    """
+    new_sents = _sentences(text)
+    if not new_sents or not quarantined_texts:
+        return None
+    tainted_sents: list[frozenset[str]] = []
+    tainted_raw: list[str] = []
+    for qt in quarantined_texts:
+        for s in _sentences(qt):
+            toks = _token_set(s)
+            if len(toks) >= 4:
+                tainted_sents.append(toks)
+                tainted_raw.append(s)
+    if not tainted_sents:
+        return None
+    best_sim = 0.0
+    for ns in new_sents:
+        nt = _token_set(ns)
+        if not nt:
+            continue
+        low = ns.lower()
+        # verbatim-quote shortcut (the classic MINJA write-back)
+        for raw in tainted_raw:
+            if len(raw) >= 25 and raw.lower() in low:
+                return InjectionVerdict(
+                    risk="high", rules=["minja_contagion"], quarantined=quarantine,
+                    note=("Second-order injection (MINJA): verbatim quote of "
+                          "quarantined source; quarantined by contagion."))
+        for tt in tainted_sents:
+            best_sim = max(best_sim, jaccard(nt, tt))
+    if best_sim >= threshold:
+        return InjectionVerdict(
+            risk="high", rules=["minja_contagion"], quarantined=quarantine,
+            note=(f"Second-order injection (MINJA): {best_sim:.0%} token "
+                  "overlap with quarantined source; quarantined by contagion."))
+    return None

cortexm/security/mind.py

@@ -0,0 +1,154 @@
+"""MIND-style retrieval diversity defense against InjecMEM.
+
+arXiv:2608.23471 (InjecMEM, August 2026) attack taxonomy:
+  * Retriever-agnostic anchors — high-recall topical cues that
+    guarantee the poisoned record surfaces in top-k
+  * Adversarial commands optimized via gradient-based coordinate
+    search (Multi-GCG)
+  * Achieves 76.6% conditional ASR when poisoned records are retrieved
+
+arXiv:2607.28103 (MIND) defense:
+  * Intent-aware Information Bottleneck extracts compact intent-
+    behavior representations from multi-turn trajectories
+  * Detects poisoned memories by measuring deviation between initial
+    user intent and subsequent behavior — exactly the signal InjecMEM
+    exploits
+  * MIND achieves the lowest ASR (19.57%) while preserving task
+    accuracy and running 20.6% faster than LLM auditing
+
+We can't ship the full MIND (it requires a learned intent encoder).
+But we CAN ship the SECONDARY signal MIND relies on: retrieval
+diversity scoring.
+
+InjecMEM relies on centroid anchors that CLUSTER in embedding space —
+the attacker wants multiple poisoned records to surface so the LLM
+sees the malicious instruction reinforced. If the top-k results are
+all too similar (low intra-result diversity), that's a strong signal
+of anchor-based poisoning.
+
+This module exposes:
+  * retrieval_diversity(facts, embedder) — mean pairwise cosine sim
+    among the top-k results. High mean = low diversity = suspect.
+  * mind_check(facts, embedder, threshold) — returns a MINDVerdict
+    with .flagged=True if diversity is too low.
+  * augment_provenance(result, mind_verdict) — stamps the retrieval
+    result's provenance with the diversity score so downstream audit
+    dashboards can surface flagged retrievals.
+
+This is μ=0 compatible — pure embedding math, no learned weights, no
+LLM call. The existing InjecMEM (regex + contagion) and MINJA
+(taint) defenses remain unchanged; MIND diversity is a third layer
+that catches what they miss: gradient-optimized adversarial text
+that is semantically coherent until retrieved.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Iterable
+
+import numpy as np
+
+from cortexm.bridge.rerank import fact_nl
+from cortexm.trace.fact import Fact
+
+
+@dataclass
+class MINDVerdict:
+    """MIND diversity check verdict.
+
+    diversity: float in [0,1] — mean pairwise cosine sim among top-k.
+                 1.0 = all facts identical (maximally suspect)
+                 0.0 = all facts orthogonal (maximally diverse)
+    flagged: True if diversity > threshold (low diversity = suspect)
+    reason: human-readable explanation
+    """
+    diversity: float = 0.0
+    flagged: bool = False
+    threshold: float = 0.85
+    n_facts: int = 0
+    reason: str = ""
+    fact_ids: list[str] = field(default_factory=list)
+
+
+def _cosine_matrix(embs: np.ndarray) -> np.ndarray:
+    """All-pairs cosine sim. Assumes embs are L2-normalized (HashingEmbedder
+    guarantees this). Falls back to manual normalization for safety.
+    """
+    norms = np.linalg.norm(embs, axis=1, keepdims=True)
+    norms = np.where(norms == 0, 1.0, norms)
+    embs_n = embs / norms
+    return embs_n @ embs_n.T
+
+
+def retrieval_diversity(facts: list[Fact], embedder,
+                         use_fact_nl: bool = True) -> float:
+    """Mean pairwise cosine similarity among the top-k retrieved facts.
+
+    Lower = more diverse = healthier.
+    Higher = more clustered = suspect (possible InjecMEM anchor).
+    """
+    if len(facts) < 2:
+        return 0.0
+    embs = []
+    for f in facts:
+        try:
+            text = fact_nl(f) if use_fact_nl else f.value
+            embs.append(embedder.embed(text))
+        except Exception:
+            v = np.zeros(getattr(embedder, "dims", 768), dtype=np.float32)
+            for i, ch in enumerate((f.value or "")[:768]):
+                v[i] = (ord(ch) % 7 - 3) / 3.0
+            embs.append(v)
+    mat = _cosine_matrix(np.stack(embs))
+    n = mat.shape[0]
+    iu = np.triu_indices(n, k=1)
+    return float(np.mean(mat[iu]))
+
+
+def mind_check(facts: list[Fact], embedder,
+               threshold: float = 0.85,
+               min_facts: int = 2,
+               flag_on_low_diversity: bool = True) -> MINDVerdict:
+    """Run the MIND diversity check on a retrieval result."""
+    if len(facts) < min_facts:
+        return MINDVerdict(
+            diversity=0.0, flagged=False, threshold=threshold,
+            n_facts=len(facts),
+            reason=f"too few facts ({len(facts)} < {min_facts}) to "
+                   f"compute diversity",
+            fact_ids=[f.id for f in facts])
+    div = retrieval_diversity(facts, embedder)
+    flagged = flag_on_low_diversity and div > threshold
+    reason = (
+        f"diversity={div:.3f} (threshold={threshold:.3f}) — "
+        + ("FLAGGED: low diversity suggests possible InjecMEM "
+           "anchor-based poisoning; recommend audit."
+           if flagged else
+           "OK: retrieval set is sufficiently diverse.")
+    )
+    return MINDVerdict(
+        diversity=div, flagged=flagged, threshold=threshold,
+        n_facts=len(facts), reason=reason,
+        fact_ids=[f.id for f in facts])
+
+
+def augment_provenance(result, verdict: MINDVerdict) -> None:
+    """Stamp a RetrievalResult's provenance with the MIND diversity score."""
+    try:
+        if hasattr(result, "provenance") and isinstance(
+                result.provenance, dict):
+            result.provenance["mind_diversity"] = round(verdict.diversity, 4)
+            result.provenance["mind_flagged"] = verdict.flagged
+            result.provenance["mind_threshold"] = verdict.threshold
+            if verdict.flagged:
+                result.provenance["mind_reason"] = verdict.reason
+    except Exception:
+        pass
+
+
+__all__ = [
+    "MINDVerdict",
+    "retrieval_diversity",
+    "mind_check",
+    "augment_provenance",
+]

cortexm/security/pii.py

@@ -0,0 +1,265 @@
+"""PII detection, redaction, and reversible tokenization (GDPR/CCPA).
+
+Enterprises cannot ship a memory layer that spreads personal data across
+every table. This module runs on the WRITE path (before extraction), so
+raw PII never reaches the Trace, the Palace, or the vector codec — the
+deterministic extractor only ever sees surrogate tokens.
+
+Modes:
+  off     — pass-through (development default; μ=0 benchmarks use this)
+  redact  — replace spans with typed tokens ``«PII:EMAIL:7f3a»``; the
+            mapping lives in a vault (encrypted at rest when a master
+            key is configured) so authorised re-identification stays
+            possible (e.g. DSAR subject-access requests)
+  block   — refuse the message entirely (strict exfiltration guard)
+
+Detectors are regex + checksum based (Luhn for cards, mod-97 for IBAN,
+SSN area/group rules) — zero LLM calls, keeping the μ=0 protocol intact.
+"""
+
+from __future__ import annotations
+
+import re
+import secrets
+from dataclasses import dataclass, field
+
+# ---------------------------------------------------------------- detectors
+_LUHN_OK: set[str] = set()  # memoized card prefixes that pass Luhn
+
+
+def _luhn_ok(digits: str) -> bool:
+    total, alt = 0, False
+    for ch in reversed(digits):
+        d = ord(ch) - 48
+        if alt:
+            d *= 2
+            if d > 9:
+                d -= 9
+        total += d
+        alt = not alt
+    return total % 10 == 0
+
+
+def _iban_ok(s: str) -> bool:
+    s = re.sub(r"\s", "", s).upper()
+    if len(s) < 15 or not s[:2].isalpha() or not s[2:].isdigit() or len(s) > 34:
+        return False
+    rearranged = s[4:] + s[:4]
+    total = 0
+    for ch in rearranged:
+        total = (total * (36 if ch.isalpha() else 10) +
+                 (ord(ch) - (55 if ch.isalpha() else 48))) % 97
+    return total == 1
+
+
+def _ssn_ok(s: str) -> bool:
+    digits = re.sub(r"\D", "", s)
+    if len(digits) != 9:
+        return False
+    area, group, serial = int(digits[0:3]), int(digits[3:5]), int(digits[5:9])
+    return not (area in (0, 666) or area >= 900) and group != 0 and serial != 0
+
+
+@dataclass
+class Span:
+    kind: str
+    start: int
+    end: int
+    text: str
+    token: str = ""
+
+
+DETECTORS: list[tuple[str, re.Pattern]] = [
+    # order matters: earlier patterns claim overlapping spans first
+    ("EMAIL", re.compile(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b")),
+    ("IBAN", re.compile(r"\b[A-Z]{2}\d{2}(?:\s?[A-Z0-9]{4}){2,7}\b")),
+    ("CREDIT_CARD", re.compile(r"\b(?:\d[ -]?){13,19}\b")),
+    ("PHONE", re.compile(r"(?:\+\d{1,3}[\s.-]?)?(?:\(\d{2,4}\)[\s.-]?)?"
+                         r"\d{3,4}[\s.-]?\d{3,4}(?:[\s.-]?\d{2,4})?\b")),
+    ("SSN", re.compile(r"\b\d{3}-\d{2}-\d{4}\b")),
+    ("IP", re.compile(r"\b(?:(?:25[0-5]|2[0-4]\d|1?\d?\d)\.){3}"
+                      r"(?:25[0-5]|2[0-4]\d|1?\d?\d)\b")),
+    ("API_KEY", re.compile(r"\b(?:sk-[A-Za-z0-9]{20,}|ghp_[A-Za-z0-9]{36}|"
+                           r"gho_[A-Za-z0-9]{36}|xox[baprs]-[A-Za-z0-9-]{10,}|"
+                           r"AKIA[0-9A-Z]{16}|AIza[0-9A-Za-z_-]{35})\b")),
+    ("PASSPORT", re.compile(r"\b[A-Z]{1,2}\d{6,9}\b(?![\w-])")),
+]
+
+_CHECKS = {"CREDIT_CARD": lambda t: _luhn_ok(re.sub(r"[ -]", "", t)),
+           "IBAN": _iban_ok,
+           "SSN": _ssn_ok,
+           "IP": lambda t: True}
+
+
+def scan(text: str) -> list[Span]:
+    """All validated PII spans in ``text``, left-to-right, non-overlapping."""
+    out: list[Span] = []
+    taken: list[tuple[int, int]] = []
+
+    def overlaps(s: int, e: int) -> bool:
+        return any(not (e <= a or s >= b) for a, b in taken)
+
+    for kind, rx in DETECTORS:
+        for m in rx.finditer(text):
+            if overlaps(m.start(), m.end()):
+                continue
+            raw = m.group(0)
+            check = _CHECKS.get(kind)
+            # card-shaped spans are claimed even on checksum failure —
+            # otherwise their digits get reinterpreted as a phone number
+            claim = kind == "CREDIT_CARD"
+            if claim:
+                taken.append((m.start(), m.end()))
+            if check and not check(raw):
+                continue
+            # phone sanity: needs >= 7 digits total and a separator/space or +
+            if kind == "PHONE":
+                digits = re.sub(r"\D", "", raw)
+                if len(digits) < 7 or len(digits) > 15:
+                    continue
+                if not re.search(r"[+\s().-]", raw) and len(digits) <= 9 \
+                        and not raw.startswith("+"):
+                    continue  # bare short number — probably an id, not a phone
+            out.append(Span(kind, m.start(), m.end(), raw))
+            taken.append((m.start(), m.end()))
+    out.sort(key=lambda s: s.start)
+    return out
+
+
+# ---------------------------------------------------------------- vault
+class PIIVault:
+    """Reversible token vault. ``token -> original`` lives in the kv store,
+    optionally encrypted with the master key (AES-256-GCM). Crypto-shredding
+    the vault key renders every token permanently unrecoverable."""
+
+    def __init__(self, store, cipher=None) -> None:
+        self.store = store          # TraceStore (kv table)
+        self.cipher = cipher        # cortexm.security.crypto.AESGCMCipher | None
+        self._counter_key = "pii:vault:counter"
+
+    def _next_id(self) -> str:
+        cur = int(self.store.kv_get(self._counter_key, "0") or "0")
+        self.store.kv_set(self._counter_key, str(cur + 1))
+        return f"{cur + 1:04x}"
+
+    def tokenize(self, kind: str, original: str) -> str:
+        """Store original, return stable token. Deterministic per original
+        (same value -> same token) so contradictions still resolve."""
+        digest = None
+        raw_index = self.store.kv_get("pii:vault:index") or "{}"
+        import json
+        try:
+            index = json.loads(raw_index)
+        except Exception:
+            index = {}
+        # index maps sha256-ish hash -> token id (avoid storing plaintext key)
+        from cortexm.security.hashes import HashProvider
+        h = HashProvider("blake2b").hash_text(original)[:24]
+        if h in index:
+            return f"«PII:{kind}:{index[h]}»"
+        tid = self._next_id()
+        index[h] = tid
+        self.store.kv_set("pii:vault:index", json.dumps(index))
+        payload = original
+        if self.cipher is not None:
+            payload = self.cipher.encrypt_str(original)
+        self.store.kv_set(f"pii:vault:{tid}", payload)
+        return f"«PII:{kind}:{tid}»"
+
+    def resolve(self, token: str) -> str | None:
+        """Token -> original (DSAR / subject-access path)."""
+        m = re.fullmatch(r"«PII:(\w+):([0-9a-f]+)»", token)
+        if not m:
+            return None
+        payload = self.store.kv_get(f"pii:vault:{m.group(2)}")
+        if payload is None:
+            return None
+        if self.cipher is not None and not payload.startswith("«enc:"):
+            return None  # vault not encrypted but cipher set — mismatch
+        if self.cipher is not None:
+            return self.cipher.decrypt_str(payload)
+        return payload
+
+    def crypto_shred(self) -> int:
+        """Destroy recoverability of every vault entry (GDPR erasure).
+        Returns number of tokens shredded."""
+        import json
+        raw_index = self.store.kv_get("pii:vault:index") or "{}"
+        try:
+            index = json.loads(raw_index)
+        except Exception:
+            index = {}
+        n = 0
+        for _h, tid in index.items():
+            if self.store.kv_get(f"pii:vault:{tid}") is not None:
+                n += 1
+            self.store.kv_set(f"pii:vault:{tid}",
+                              "«shredded»" if self.cipher is None
+                              else self.cipher.encrypt_str("«shredded»"))
+        # rotate the index so old tokens cannot be re-linked
+        self.store.kv_set("pii:vault:index", "{}")
+        self.store.kv_set(self._counter_key, "0")
+        return n
+
+    def stats(self) -> dict:
+        import json
+        raw_index = self.store.kv_get("pii:vault:index") or "{}"
+        try:
+            n = len(json.loads(raw_index))
+        except Exception:
+            n = 0
+        return {"vault_entries": n, "encrypted": self.cipher is not None}
+
+
+# ---------------------------------------------------------------- engine
+@dataclass
+class PIIResult:
+    mode: str
+    blocked: bool = False
+    redacted_text: str = ""
+    spans: list[Span] = field(default_factory=list)
+    tokens: list[str] = field(default_factory=list)
+
+
+class PIIGuard:
+    """Write-path PII policy engine."""
+
+    def __init__(self, mode: str = "off", vault: PIIVault | None = None) -> None:
+        if mode not in ("off", "redact", "block", "tag"):
+            raise ValueError(f"unknown pii mode {mode!r}")
+        self.mode = mode
+        self.vault = vault
+
+    def process(self, text: str) -> PIIResult:
+        res = PIIResult(mode=self.mode, redacted_text=text)
+        if self.mode == "off" or not text:
+            return res
+        res.spans = scan(text)
+        if not res.spans:
+            return res
+        if self.mode == "block":
+            res.blocked = True
+            return res
+        if self.mode == "tag":
+            res.tokens = [f"{s.kind}" for s in res.spans]
+            return res
+        # redact: right-to-left replacement so indices stay valid
+        out = text
+        for s in reversed(res.spans):
+            if self.vault is not None:
+                token = self.vault.tokenize(s.kind, s.text)
+                s.token = token
+                res.tokens.append(token)
+                out = out[:s.start] + token + out[s.end:]
+            else:
+                out = out[:s.start] + f"«PII:{s.kind}»" + out[s.end:]
+        res.redacted_text = out
+        return res
+
+
+def redact_inplace(text: str) -> str:
+    """Stateless helper: mask without vault (irreversible)."""
+    out = text
+    for s in reversed(scan(text)):
+        out = out[:s.start] + f"«PII:{s.kind}»" + out[s.end:]
+    return out