@rulemetric/proxy 0.2.2

package/addon/security_scanner.py

@@ -0,0 +1,828 @@
+"""Security scanner integration for the RuleMetric mitmproxy addon.
+
+Uses LLM Guard (from Protect AI) to scan LLM API traffic for:
+  - Prompt injection attacks
+  - Leaked secrets (API keys, tokens)
+  - Personally identifiable information (PII)
+
+Two operating modes:
+  OBSERVE  - Non-blocking. Scans a copy of the request in a background thread.
+             Results are reported asynchronously to the RuleMetric API.
+             Adds zero latency to the proxy pipeline.
+
+  BLOCK    - Synchronous. Scans inline during the mitmproxy request() hook.
+             If a scanner flags the request above its configured threshold,
+             the request is killed and a synthetic 403 response is returned.
+             Adds ~50-200ms latency per request (model-dependent).
+
+Configuration is driven by environment variables and an optional JSON config
+file. Scanner failures never break the proxy -- all scanner calls are wrapped
+in try/except with structured logging.
+
+Architecture notes
+------------------
+LLM Guard scanners are CPU-bound (they load small ML models via transformers).
+First call per scanner triggers model download + load (~2-5s). Subsequent calls
+run inference at ~20-100ms for PromptInjection, ~5-20ms for Secrets/Anonymize.
+
+For OBSERVE mode we run scans on a dedicated ThreadPoolExecutor so the
+mitmproxy event loop is never blocked. For BLOCK mode we run scans inline
+in the request() hook -- mitmproxy's request hooks are synchronous, so this
+is the correct place to intercept.
+
+LLM Guard Python API (from llm_guard >= 0.3.14):
+    from llm_guard.input_scanners import PromptInjection, Secrets, Anonymize
+    scanner = PromptInjection(threshold=0.9)
+    sanitized_output, is_valid, risk_score = scanner.scan(prompt)
+      - sanitized_output: str  -- the (possibly redacted) text
+      - is_valid: bool         -- True if the text passed the scan
+      - risk_score: float      -- 0.0 (clean) to 1.0 (dangerous)
+
+Dependencies (add to requirements.txt when ready to activate):
+    llm-guard>=0.3.14
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from typing import Any
+
+from mitmproxy import http
+
+logger = logging.getLogger("rulemetric.security_scanner")
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+# Env-var overrides (simple, twelve-factor friendly)
+#   RULEMETRIC_SCANNER_MODE        = "observe" | "block" | "off"
+#   RULEMETRIC_SCANNER_CONFIG_PATH = path to JSON config (optional)
+#   RULEMETRIC_SCANNER_WORKERS     = number of background threads (observe mode)
+
+DEFAULT_CONFIG: dict[str, Any] = {
+    # Global mode: "observe" (async, non-blocking), "block" (sync), "off"
+    "mode": "observe",
+
+    # Per-scanner config. Set "enabled": false to skip a scanner entirely.
+    "scanners": {
+        "prompt_injection": {
+            "enabled": True,
+            # Threshold above which we consider the input malicious.
+            # LLM Guard's PromptInjection returns risk_score 0.0-1.0.
+            # Default model: ProtectAI/deberta-v3-base-prompt-injection-v2
+            "threshold": 0.90,
+            # Which model to use (None = LLM Guard default).
+            "model": None,
+        },
+        "secrets": {
+            "enabled": True,
+            # Secrets scanner uses regex + entropy analysis -- no ML model.
+            # The threshold here is for the aggregate confidence.
+            "threshold": 0.80,
+            # Redact detected secrets in observe-mode reports.
+            "redact_in_report": True,
+        },
+        "pii": {
+            "enabled": True,
+            # PII / Anonymize scanner detects emails, phone numbers, SSNs, etc.
+            # Uses Presidio under the hood (spaCy NER + regex).
+            "threshold": 0.70,
+            # Which entity types to detect. None = all defaults.
+            # Options: EMAIL_ADDRESS, PHONE_NUMBER, CREDIT_CARD, US_SSN, etc.
+            "entity_types": None,
+            "redact_in_report": True,
+        },
+    },
+
+    # Background thread pool size for observe mode.
+    "worker_threads": 2,
+
+    # Maximum prompt length to scan (chars). Truncate longer prompts to avoid
+    # excessive latency on very large context windows.
+    "max_scan_length": 50_000,
+}
+
+
+@dataclass
+class ScanResult:
+    """Result from a single scanner run."""
+    scanner_name: str
+    is_valid: bool
+    risk_score: float
+    # Wall-clock time for this scan in milliseconds.
+    latency_ms: float
+    # Details about what was found (e.g., list of detected entity types).
+    details: dict[str, Any] = field(default_factory=dict)
+    # Error message if the scanner itself failed.
+    error: str | None = None
+
+
+@dataclass
+class ScanReport:
+    """Aggregated results across all scanners for a single request."""
+    flow_id: str
+    mode: str  # "observe" or "block"
+    timestamp: str
+    # True if all scanners passed; False if any flagged the input.
+    passed: bool
+    results: list[ScanResult] = field(default_factory=list)
+    # Total scan latency across all scanners in milliseconds.
+    total_latency_ms: float = 0.0
+    # The prompt text that was scanned (truncated for storage).
+    prompt_preview: str = ""
+
+
+# ---------------------------------------------------------------------------
+# Scanner wrapper (lazy-loads llm_guard on first use)
+# ---------------------------------------------------------------------------
+
+class _ScannerPool:
+    """Lazy-initializing pool of LLM Guard scanners.
+
+    Scanners are heavyweight (they load ML models into memory), so we create
+    them once and reuse across requests. Initialization is thread-safe.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._initialized = False
+        self._prompt_injection = None
+        self._secrets = None
+        self._pii = None
+        self._available = False
+
+    def _init_scanners(self, config: dict[str, Any]) -> None:
+        """Import llm_guard and create scanner instances.
+
+        Called once, guarded by lock. If llm_guard is not installed, all
+        scanners remain None and _available stays False.
+        """
+        if self._initialized:
+            return
+
+        with self._lock:
+            if self._initialized:
+                return
+
+            try:
+                # ----------------------------------------------------------
+                # PromptInjection scanner
+                # ----------------------------------------------------------
+                pi_cfg = config.get("scanners", {}).get("prompt_injection", {})
+                if pi_cfg.get("enabled", True):
+                    from llm_guard.input_scanners import PromptInjection
+
+                    kwargs: dict[str, Any] = {
+                        "threshold": pi_cfg.get("threshold", 0.90),
+                    }
+                    model_name = pi_cfg.get("model")
+                    if model_name:
+                        kwargs["model"] = model_name
+
+                    self._prompt_injection = PromptInjection(**kwargs)
+                    logger.info(
+                        "PromptInjection scanner loaded (threshold=%.2f)",
+                        kwargs["threshold"],
+                    )
+
+                # ----------------------------------------------------------
+                # Secrets scanner
+                # ----------------------------------------------------------
+                sec_cfg = config.get("scanners", {}).get("secrets", {})
+                if sec_cfg.get("enabled", True):
+                    from llm_guard.input_scanners import Secrets
+
+                    self._secrets = Secrets(
+                        redact=sec_cfg.get("redact_in_report", True),
+                    )
+                    logger.info("Secrets scanner loaded")
+
+                # ----------------------------------------------------------
+                # PII / Anonymize scanner
+                # ----------------------------------------------------------
+                pii_cfg = config.get("scanners", {}).get("pii", {})
+                if pii_cfg.get("enabled", True):
+                    from llm_guard.input_scanners import Anonymize
+
+                    kwargs_pii: dict[str, Any] = {}
+                    entity_types = pii_cfg.get("entity_types")
+                    if entity_types:
+                        kwargs_pii["allowed_names"] = entity_types
+
+                    self._pii = Anonymize(**kwargs_pii)
+                    logger.info("PII/Anonymize scanner loaded")
+
+                self._available = True
+                logger.info("LLM Guard scanners initialized successfully")
+
+            except ImportError as exc:
+                logger.warning(
+                    "llm_guard is not installed -- security scanning is disabled. "
+                    "Install with: pip install llm-guard>=0.3.14  (%s)",
+                    exc,
+                )
+                self._available = False
+            except Exception as exc:
+                logger.error(
+                    "Failed to initialize LLM Guard scanners: %s", exc, exc_info=True
+                )
+                self._available = False
+            finally:
+                self._initialized = True
+
+    @property
+    def available(self) -> bool:
+        return self._available
+
+    def scan_prompt_injection(self, text: str, threshold: float) -> ScanResult:
+        """Run the PromptInjection scanner."""
+        if self._prompt_injection is None:
+            return ScanResult(
+                scanner_name="prompt_injection",
+                is_valid=True,
+                risk_score=0.0,
+                latency_ms=0.0,
+                details={"skipped": True, "reason": "scanner not loaded"},
+            )
+
+        t0 = time.monotonic()
+        try:
+            sanitized, is_valid, risk_score = self._prompt_injection.scan(text)
+            latency = (time.monotonic() - t0) * 1000
+            return ScanResult(
+                scanner_name="prompt_injection",
+                is_valid=is_valid,
+                risk_score=risk_score,
+                latency_ms=latency,
+                details={
+                    "flagged": not is_valid,
+                    "threshold": threshold,
+                },
+            )
+        except Exception as exc:
+            latency = (time.monotonic() - t0) * 1000
+            logger.error("PromptInjection scanner error: %s", exc, exc_info=True)
+            return ScanResult(
+                scanner_name="prompt_injection",
+                is_valid=True,  # Fail open -- don't block on scanner errors
+                risk_score=0.0,
+                latency_ms=latency,
+                error=str(exc),
+            )
+
+    def scan_secrets(self, text: str, threshold: float) -> ScanResult:
+        """Run the Secrets scanner."""
+        if self._secrets is None:
+            return ScanResult(
+                scanner_name="secrets",
+                is_valid=True,
+                risk_score=0.0,
+                latency_ms=0.0,
+                details={"skipped": True, "reason": "scanner not loaded"},
+            )
+
+        t0 = time.monotonic()
+        try:
+            sanitized, is_valid, risk_score = self._secrets.scan(text)
+            latency = (time.monotonic() - t0) * 1000
+            return ScanResult(
+                scanner_name="secrets",
+                is_valid=is_valid,
+                risk_score=risk_score,
+                latency_ms=latency,
+                details={
+                    "flagged": not is_valid,
+                    "threshold": threshold,
+                    # Include redacted text preview when secrets are found
+                    "redacted_preview": sanitized[:200] if not is_valid else None,
+                },
+            )
+        except Exception as exc:
+            latency = (time.monotonic() - t0) * 1000
+            logger.error("Secrets scanner error: %s", exc, exc_info=True)
+            return ScanResult(
+                scanner_name="secrets",
+                is_valid=True,
+                risk_score=0.0,
+                latency_ms=latency,
+                error=str(exc),
+            )
+
+    def scan_pii(self, text: str, threshold: float) -> ScanResult:
+        """Run the PII / Anonymize scanner."""
+        if self._pii is None:
+            return ScanResult(
+                scanner_name="pii",
+                is_valid=True,
+                risk_score=0.0,
+                latency_ms=0.0,
+                details={"skipped": True, "reason": "scanner not loaded"},
+            )
+
+        t0 = time.monotonic()
+        try:
+            sanitized, is_valid, risk_score = self._pii.scan(text)
+            latency = (time.monotonic() - t0) * 1000
+            return ScanResult(
+                scanner_name="pii",
+                is_valid=True if risk_score < threshold else False,
+                risk_score=risk_score,
+                latency_ms=latency,
+                details={
+                    "flagged": risk_score >= threshold,
+                    "threshold": threshold,
+                    "redacted_preview": sanitized[:200] if risk_score >= threshold else None,
+                },
+            )
+        except Exception as exc:
+            latency = (time.monotonic() - t0) * 1000
+            logger.error("PII scanner error: %s", exc, exc_info=True)
+            return ScanResult(
+                scanner_name="pii",
+                is_valid=True,
+                risk_score=0.0,
+                latency_ms=latency,
+                error=str(exc),
+            )
+
+
+# Module-level singleton -- created once, shared across all flows.
+_scanner_pool = _ScannerPool()
+
+
+# ---------------------------------------------------------------------------
+# Config loader
+# ---------------------------------------------------------------------------
+
+def _load_config() -> dict[str, Any]:
+    """Load scanner config from env vars and optional JSON file.
+
+    Priority: env var overrides > JSON file > DEFAULT_CONFIG.
+    """
+    config = dict(DEFAULT_CONFIG)
+
+    # Load JSON config file if specified
+    config_path = os.environ.get("RULEMETRIC_SCANNER_CONFIG_PATH")
+    if config_path:
+        try:
+            with open(config_path) as f:
+                file_config = json.load(f)
+            # Deep-merge scanner configs
+            for key in ("mode", "worker_threads", "max_scan_length"):
+                if key in file_config:
+                    config[key] = file_config[key]
+            if "scanners" in file_config:
+                for scanner_name, scanner_cfg in file_config["scanners"].items():
+                    if scanner_name in config["scanners"]:
+                        config["scanners"][scanner_name].update(scanner_cfg)
+                    else:
+                        config["scanners"][scanner_name] = scanner_cfg
+            logger.info("Loaded scanner config from %s", config_path)
+        except (OSError, json.JSONDecodeError) as exc:
+            logger.warning("Failed to load scanner config from %s: %s", config_path, exc)
+
+    # Env var overrides
+    mode = os.environ.get("RULEMETRIC_SCANNER_MODE")
+    if mode:
+        config["mode"] = mode.lower()
+
+    workers = os.environ.get("RULEMETRIC_SCANNER_WORKERS")
+    if workers:
+        try:
+            config["worker_threads"] = int(workers)
+        except ValueError:
+            pass
+
+    return config
+
+
+# ---------------------------------------------------------------------------
+# Core scan logic
+# ---------------------------------------------------------------------------
+
+def _extract_scannable_text(flow: http.HTTPFlow) -> str | None:
+    """Extract the user-facing prompt text from an LLM API request body.
+
+    Returns a single string combining system prompt + user messages,
+    which is what we want to scan for injections, secrets, and PII.
+    Returns None if the body can't be parsed.
+    """
+    body_text = flow.request.get_text()
+    if not body_text:
+        return None
+
+    try:
+        body = json.loads(body_text)
+    except (json.JSONDecodeError, ValueError):
+        return None
+
+    parts: list[str] = []
+
+    # Anthropic format
+    system = body.get("system", "")
+    if isinstance(system, list):
+        for block in system:
+            if isinstance(block, dict):
+                parts.append(block.get("text", ""))
+    elif system:
+        parts.append(str(system))
+
+    # OpenAI / generic format -- messages array
+    for msg in body.get("messages", []):
+        content = msg.get("content", "")
+        if isinstance(content, str):
+            parts.append(content)
+        elif isinstance(content, list):
+            for block in content:
+                if isinstance(block, dict):
+                    parts.append(block.get("text", ""))
+
+    # Gemini format -- systemInstruction + contents
+    sys_instr = body.get("systemInstruction", {})
+    if isinstance(sys_instr, dict):
+        for part in sys_instr.get("parts", []):
+            if isinstance(part, dict):
+                parts.append(part.get("text", ""))
+
+    for content_item in body.get("contents", []):
+        if isinstance(content_item, dict):
+            for part in content_item.get("parts", []):
+                if isinstance(part, dict) and "text" in part:
+                    parts.append(part["text"])
+
+    combined = "\n".join(p for p in parts if p)
+    return combined if combined else None
+
+
+def _run_all_scanners(text: str, config: dict[str, Any]) -> list[ScanResult]:
+    """Run all enabled scanners against the given text. Returns list of results."""
+    results: list[ScanResult] = []
+    scanners_cfg = config.get("scanners", {})
+
+    max_len = config.get("max_scan_length", 50_000)
+    scan_text = text[:max_len] if len(text) > max_len else text
+
+    # PromptInjection
+    pi_cfg = scanners_cfg.get("prompt_injection", {})
+    if pi_cfg.get("enabled", True):
+        results.append(
+            _scanner_pool.scan_prompt_injection(
+                scan_text,
+                threshold=pi_cfg.get("threshold", 0.90),
+            )
+        )
+
+    # Secrets
+    sec_cfg = scanners_cfg.get("secrets", {})
+    if sec_cfg.get("enabled", True):
+        results.append(
+            _scanner_pool.scan_secrets(
+                scan_text,
+                threshold=sec_cfg.get("threshold", 0.80),
+            )
+        )
+
+    # PII
+    pii_cfg = scanners_cfg.get("pii", {})
+    if pii_cfg.get("enabled", True):
+        results.append(
+            _scanner_pool.scan_pii(
+                scan_text,
+                threshold=pii_cfg.get("threshold", 0.70),
+            )
+        )
+
+    return results
+
+
+def _build_report(
+    flow_id: str,
+    mode: str,
+    results: list[ScanResult],
+    prompt_text: str,
+) -> ScanReport:
+    """Build an aggregated scan report from individual scanner results."""
+    from datetime import datetime, timezone
+
+    total_latency = sum(r.latency_ms for r in results)
+    all_passed = all(r.is_valid for r in results)
+
+    return ScanReport(
+        flow_id=flow_id,
+        mode=mode,
+        timestamp=datetime.now(timezone.utc).isoformat(),
+        passed=all_passed,
+        results=results,
+        total_latency_ms=total_latency,
+        prompt_preview=prompt_text[:500],
+    )
+
+
+# ---------------------------------------------------------------------------
+# Report delivery (async, reuses reporter's pattern)
+# ---------------------------------------------------------------------------
+
+def _report_scan_results(session_id: str | None, report: ScanReport) -> None:
+    """Post scan results to the RuleMetric API as a session event.
+
+    This runs in a background thread (fire-and-forget), matching the pattern
+    used by reporter.py for snapshots and events.
+    """
+    if not session_id:
+        logger.debug("No session ID -- scan report dropped")
+        return
+
+    try:
+        from reporter import report_event
+    except ImportError:
+        logger.debug("reporter module not available -- scan report dropped")
+        return
+
+    event = {
+        "eventType": "security_scan",
+        "timestamp": report.timestamp,
+        "metadata": {
+            "mode": report.mode,
+            "passed": report.passed,
+            "total_latency_ms": round(report.total_latency_ms, 1),
+            "scanners": [
+                {
+                    "name": r.scanner_name,
+                    "is_valid": r.is_valid,
+                    "risk_score": round(r.risk_score, 4),
+                    "latency_ms": round(r.latency_ms, 1),
+                    "error": r.error,
+                    "details": r.details,
+                }
+                for r in report.results
+            ],
+        },
+    }
+    report_event(session_id, event)
+
+
+# ---------------------------------------------------------------------------
+# Blocking mode: synthetic error response
+# ---------------------------------------------------------------------------
+
+def _create_block_response(report: ScanReport) -> http.Response:
+    """Create a synthetic 403 response for a blocked request.
+
+    The response body is JSON that mimics an LLM API error format so that
+    downstream clients (Claude Code, etc.) can parse and display it.
+    """
+    flagged_scanners = [r for r in report.results if not r.is_valid]
+    scanner_names = [r.scanner_name for r in flagged_scanners]
+    max_risk = max((r.risk_score for r in flagged_scanners), default=0.0)
+
+    body = {
+        "error": {
+            "type": "security_scan_blocked",
+            "message": (
+                f"Request blocked by security scanner. "
+                f"Flagged by: {', '.join(scanner_names)}. "
+                f"Highest risk score: {max_risk:.2f}."
+            ),
+            "scanners": scanner_names,
+            "risk_score": round(max_risk, 4),
+        },
+    }
+
+    return http.Response.make(
+        status_code=403,
+        content=json.dumps(body).encode("utf-8"),
+        headers={
+            "Content-Type": "application/json",
+            "X-RuleMetric-Blocked": "true",
+            "X-RuleMetric-Scanner": ",".join(scanner_names),
+        },
+    )
+
+
+# ---------------------------------------------------------------------------
+# Public API -- mitmproxy addon integration
+# ---------------------------------------------------------------------------
+
+class SecurityScannerAddon:
+    """mitmproxy addon that scans LLM API traffic for security issues.
+
+    Designed to be composed with RuleMetricAddon. Add to the addons list
+    BEFORE RuleMetricAddon so it can block requests before they're captured.
+
+    Usage in rulemetric_addon.py:
+        from security_scanner import SecurityScannerAddon
+
+        addons = [SecurityScannerAddon(), RuleMetricAddon()]
+
+    Or to keep it optional:
+        addons = [RuleMetricAddon()]
+        try:
+            from security_scanner import SecurityScannerAddon
+            addons.insert(0, SecurityScannerAddon())
+        except Exception:
+            pass
+    """
+
+    def __init__(self, config: dict[str, Any] | None = None) -> None:
+        self._config = config or _load_config()
+        self._mode = self._config.get("mode", "observe")
+        self._executor: ThreadPoolExecutor | None = None
+        self._scan_count = 0
+        self._block_count = 0
+        self._stats_lock = threading.Lock()
+
+        if self._mode == "off":
+            logger.info("Security scanner is OFF (set RULEMETRIC_SCANNER_MODE=observe|block to enable)")
+            return
+
+        # Initialize scanners eagerly so model loading happens at startup,
+        # not on the first request (which would spike latency).
+        _scanner_pool._init_scanners(self._config)
+
+        if not _scanner_pool.available:
+            logger.warning("LLM Guard not available -- security scanner disabled")
+            self._mode = "off"
+            return
+
+        if self._mode == "observe":
+            worker_count = self._config.get("worker_threads", 2)
+            self._executor = ThreadPoolExecutor(
+                max_workers=worker_count,
+                thread_name_prefix="rulemetric-scanner",
+            )
+            logger.info(
+                "Security scanner initialized in OBSERVE mode (%d worker threads)",
+                worker_count,
+            )
+        elif self._mode == "block":
+            logger.info("Security scanner initialized in BLOCK mode (synchronous)")
+        else:
+            logger.warning("Unknown scanner mode '%s' -- defaulting to OFF", self._mode)
+            self._mode = "off"
+
+    def request(self, flow: http.HTTPFlow) -> None:
+        """Scan incoming LLM API requests.
+
+        In OBSERVE mode: submit scan to background thread pool, return immediately.
+        In BLOCK mode: scan inline, return synthetic 403 if flagged.
+        """
+        if self._mode == "off":
+            return
+
+        # Only scan POST requests to LLM API endpoints.
+        # Re-use the provider detection from providers.py to avoid scanning
+        # non-LLM traffic.
+        try:
+            from providers import detect_provider
+        except ImportError:
+            return
+
+        host = flow.request.pretty_host
+        path = flow.request.path
+        provider = detect_provider(host, path)
+        if provider is None:
+            return
+
+        if flow.request.method != "POST":
+            return
+
+        prompt_text = _extract_scannable_text(flow)
+        if not prompt_text:
+            return
+
+        # Find session ID for reporting (best-effort, non-critical)
+        session_id: str | None = None
+        try:
+            from session_linker import find_active_session
+            session_info = find_active_session(provider=provider)
+            if session_info:
+                session_id = session_info.get("rw_session_id") or session_info.get("session_id")
+        except Exception:
+            pass
+
+        with self._stats_lock:
+            self._scan_count += 1
+            scan_num = self._scan_count
+
+        if self._mode == "observe":
+            self._scan_observe(flow.id, prompt_text, session_id, scan_num)
+        elif self._mode == "block":
+            self._scan_block(flow, prompt_text, session_id, scan_num)
+
+    def _scan_observe(
+        self,
+        flow_id: str,
+        prompt_text: str,
+        session_id: str | None,
+        scan_num: int,
+    ) -> None:
+        """Submit scan to background thread pool. Non-blocking."""
+        if self._executor is None:
+            return
+
+        def _do_scan() -> None:
+            try:
+                results = _run_all_scanners(prompt_text, self._config)
+                report = _build_report(flow_id, "observe", results, prompt_text)
+
+                if not report.passed:
+                    flagged = [r for r in results if not r.is_valid]
+                    logger.warning(
+                        "OBSERVE scan #%d flagged by %s (risk scores: %s, latency: %.0fms)",
+                        scan_num,
+                        [r.scanner_name for r in flagged],
+                        [round(r.risk_score, 3) for r in flagged],
+                        report.total_latency_ms,
+                    )
+                else:
+                    logger.debug(
+                        "OBSERVE scan #%d passed all scanners (latency: %.0fms)",
+                        scan_num,
+                        report.total_latency_ms,
+                    )
+
+                # Report results asynchronously
+                _report_scan_results(session_id, report)
+            except Exception as exc:
+                logger.error(
+                    "Background scan #%d failed: %s", scan_num, exc, exc_info=True
+                )
+
+        self._executor.submit(_do_scan)
+
+    def _scan_block(
+        self,
+        flow: http.HTTPFlow,
+        prompt_text: str,
+        session_id: str | None,
+        scan_num: int,
+    ) -> None:
+        """Scan inline (synchronous). Block request if flagged."""
+        try:
+            results = _run_all_scanners(prompt_text, self._config)
+            report = _build_report(flow.id, "block", results, prompt_text)
+
+            if not report.passed:
+                flagged = [r for r in results if not r.is_valid]
+                logger.warning(
+                    "BLOCK scan #%d BLOCKED by %s (risk scores: %s, latency: %.0fms)",
+                    scan_num,
+                    [r.scanner_name for r in flagged],
+                    [round(r.risk_score, 3) for r in flagged],
+                    report.total_latency_ms,
+                )
+
+                # Kill the flow and return a synthetic 403 response.
+                # mitmproxy's flow.response assignment prevents the request
+                # from being forwarded to the upstream server.
+                flow.response = _create_block_response(report)
+
+                with self._stats_lock:
+                    self._block_count += 1
+
+                # Still report the block event
+                _report_scan_results(session_id, report)
+            else:
+                logger.debug(
+                    "BLOCK scan #%d passed (latency: %.0fms)",
+                    scan_num,
+                    report.total_latency_ms,
+                )
+                # Optionally report clean scans too (for audit trail)
+                _report_scan_results(session_id, report)
+
+        except Exception as exc:
+            # Fail open -- if scanning crashes, let the request through.
+            logger.error(
+                "BLOCK scan #%d error (failing open): %s",
+                scan_num,
+                exc,
+                exc_info=True,
+            )
+
+    def get_stats(self) -> dict[str, Any]:
+        """Return scanner statistics for observability."""
+        with self._stats_lock:
+            return {
+                "mode": self._mode,
+                "scans": self._scan_count,
+                "blocks": self._block_count,
+                "scanners_available": _scanner_pool.available,
+            }
+
+    def done(self) -> None:
+        """Shutdown hook -- clean up the thread pool."""
+        if self._executor is not None:
+            self._executor.shutdown(wait=False)
+            logger.info(
+                "Security scanner shutdown (scans=%d, blocks=%d)",
+                self._scan_count,
+                self._block_count,
+            )