Pre-Request Enforcement Guide¶

Estimated time to read: 4 minutes

By default, LLMTrace analyses requests asynchronously after forwarding them to the upstream provider. The enforcement feature adds synchronous pre-request analysis that can block or flag requests before they reach the LLM.

Enforcement Modes¶

log (default)¶

No enforcement. Requests are forwarded immediately. Security analysis happens asynchronously. This is the default behaviour when the enforcement section is omitted from config.

block¶

Requests that trigger enforcement criteria receive a 403 Forbidden response and are not forwarded to the upstream provider.

Response body:

{
  "error": {
    "message": "Request blocked due to security policy violation",
    "type": "security_violation",
    "code": "prompt_injection_detected",
    "details": {
      "finding_type": "prompt_injection",
      "severity": "high",
      "description": "System prompt override attempt detected"
    }
  }
}

flag¶

Requests are forwarded to the upstream provider, but finding metadata is attached as response headers:

• X-LLMTrace-Flagged: true
• X-LLMTrace-Finding-Type: prompt_injection
• X-LLMTrace-Severity: high

Your application can inspect these headers and take action (e.g., log, alert, suppress the response).

Configuration¶

enforcement:
  mode: "block"              # "log" | "block" | "flag"
  analysis_depth: "fast"     # "fast" | "full"
  min_severity: "high"       # minimum severity to enforce
  min_confidence: 0.8        # minimum confidence to enforce (0.0-1.0)
  timeout_ms: 2000           # fail-open on timeout
  categories:                # per-finding-type overrides
    - finding_type: "prompt_injection"
      action: "block"
    - finding_type: "shell_injection"
      action: "block"
    - finding_type: "data_leakage"
      action: "log"

Analysis Depth¶

fast¶

Runs regex-only analysis. Near-zero added latency (microseconds). Catches known patterns but misses novel attacks.

full (default)¶

Runs the full ensemble (regex + ML models). Adds ML inference latency (typically 50-200ms depending on model count and hardware). Better detection coverage.

enforcement:
  analysis_depth: "full"

full is the default (issue #300) so the response envelope's findings[], the security_score, and the LLM-facing advisory injection see the same analyzer set that the async post-response pipeline persists onto the trace. Set analysis_depth: "fast" explicitly to opt into regex-only when latency is critical and regex coverage is sufficient.

Severity and Confidence Gates¶

Enforcement only triggers when a finding meets both the minimum severity and minimum confidence:

enforcement:
  min_severity: "high"     # info | low | medium | high | critical
  min_confidence: 0.8      # 0.0 to 1.0

A finding with severity: medium and confidence: 0.95 will not trigger enforcement if min_severity is high.

Defaults: - min_severity: high - min_confidence: 0.8

Timeout and Fail-Open¶

If enforcement analysis exceeds timeout_ms, the request is forwarded without enforcement (fail-open):

enforcement:
  timeout_ms: 5000  # 5 seconds, then fail-open

Default: 5000ms (matches the async background analysis timeout so the sync full ensemble has the same budget the async path does). This prevents enforcement from becoming a reliability bottleneck.

Per-Category Overrides¶

Override the enforcement action for specific finding types:

enforcement:
  mode: "flag"               # default action for all categories
  categories:
    - finding_type: "prompt_injection"
      action: "block"        # override: block injections
    - finding_type: "shell_injection"
      action: "block"        # override: block shell injection
    - finding_type: "pii_detected"
      action: "flag"         # flag PII but don't block
    - finding_type: "data_leakage"
      action: "log"          # just log data leakage

The categories list takes precedence over the top-level mode. Finding types not listed fall back to the top-level mode.

Example Configurations¶

Block injections, log everything else¶

enforcement:
  mode: "log"
  analysis_depth: "fast"
  min_severity: "high"
  min_confidence: 0.8
  categories:
    - finding_type: "prompt_injection"
      action: "block"
    - finding_type: "role_injection"
      action: "block"
    - finding_type: "shell_injection"
      action: "block"

Full ML enforcement with strict thresholds¶

enforcement:
  mode: "block"
  analysis_depth: "full"
  min_severity: "medium"
  min_confidence: 0.9
  timeout_ms: 5000

Flag everything for monitoring (no blocking)¶

enforcement:
  mode: "flag"
  analysis_depth: "fast"
  min_severity: "low"
  min_confidence: 0.5

Interaction with Async Analysis¶

Enforcement runs before the request is forwarded. The standard async analysis pipeline still runs after the response, regardless of enforcement settings. This means:

• Enforcement findings may appear in the security findings API before async analysis findings
• A request blocked by enforcement will still have its content analysed asynchronously for audit/logging purposes
• The async pipeline uses the full ensemble regardless of the enforcement analysis_depth setting