mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-08-17 20:52:15 +03:00
5379493bed
Implements the secure, opt-in Video Bridge for issue #9760, including bounded FFmpeg frame extraction, capability-aware routing, telemetry, settings UI, localization, documentation, and regression coverage.
679 lines
39 KiB
Markdown
679 lines
39 KiB
Markdown
---
|
||
title: "Guardrails"
|
||
version: 3.8.50
|
||
lastUpdated: 2026-08-14
|
||
---
|
||
|
||
# Guardrails
|
||
|
||
> **Source of truth:** `src/lib/guardrails/`
|
||
> **Last updated:** 2026-08-15 — v3.8.50 (Video Bridge broker confinement)
|
||
|
||
Guardrails enforce safety, policy, and content transformations at the boundary
|
||
between OmniRoute and upstream providers. Each guardrail can inspect (and
|
||
optionally reject, transform, or annotate) request payloads (`preCall`) and
|
||
upstream responses (`postCall`).
|
||
|
||
The system is **fail-open**: if a guardrail throws while executing, the registry
|
||
records the error and continues with the next guardrail rather than failing the
|
||
request. Blocking is an explicit decision (`block: true`), never an accident.
|
||
|
||
## Built-in Guardrails
|
||
|
||
The registry auto-loads six guardrails in priority order on import
|
||
(see `registry.ts` → `registerDefaultGuardrails()`):
|
||
|
||
| Priority | Name | Stage(s) | File |
|
||
| -------- | ------------------- | -------------- | --------------------- |
|
||
| `5` | `vision-bridge` | `preCall` | `visionBridge.ts` |
|
||
| `6` | `audio-bridge` | `preCall` | `audioBridge.ts` |
|
||
| `7` | `video-bridge` | `preCall` | `videoBridge.ts` |
|
||
| `10` | `pii-masker` | `pre` + `post` | `piiMasker.ts` |
|
||
| `20` | `prompt-injection` | `preCall` | `promptInjection.ts` |
|
||
| `95` | `credential-masker` | `pre` + `post` | `credentialMasker.ts` |
|
||
|
||
Lower priority numbers run **first**.
|
||
|
||
### Vision Bridge (`visionBridge.ts`) — Modality Bridge PR-1
|
||
|
||
Intercepts image-bearing requests aimed at **non-vision models** and either
|
||
reroutes the whole request to a vision-capable model or replaces the image
|
||
parts with text descriptions produced by a configurable vision model before
|
||
the upstream call. This lets text-only providers transparently handle
|
||
multimodal payloads.
|
||
|
||
Flow:
|
||
|
||
1. Skip if the target model already supports vision (unless it appears in the
|
||
forced-bridge list `isVisionBridgeForcedModel`).
|
||
2. Extract image parts via `extractImageParts(messages)`
|
||
(`visionBridgeHelpers.ts`), which delegates to the **unified media
|
||
detector** `detectMediaParts()` in `open-sse/utils/mediaParts.ts` — the
|
||
single source of truth shared with the combo compatibility filter.
|
||
Extraction is allowlisted to top-level parts of the shapes
|
||
`replaceImageParts` can splice back (the extract↔replace contract): OpenAI
|
||
`image_url`, Anthropic base64 `source.type:"base64"`, Anthropic URL
|
||
`source.type:"url"`, and Responses API `input_image`. Nested hits and
|
||
indicator-only shapes are combo-filter material and are never extracted.
|
||
Skip if none found.
|
||
3. Resolve runtime config via `resolveVisionBridgeRuntimeSettings()`
|
||
(`src/shared/constants/modalityBridgeDefaults.ts`): new `modalityBridge*`
|
||
settings keys win; legacy `visionBridge*` keys remain a **one-cycle
|
||
fallback** (rollback window). Skip before any media traversal when the
|
||
bridge is disabled.
|
||
4. Mode selector (`modalityBridgeVisionMode`, see table below) decides
|
||
reroute vs describe. Reroute returns `modifiedPayload` with only `model`
|
||
swapped, plus meta `{ rerouted, fromModel, toModel, imagesKept }`.
|
||
5. Describe path: cap images at `maxImages`, compose the task-aware prompt,
|
||
consult the describe cache, call the vision model **in parallel**
|
||
(`Promise.allSettled`), and inject `[Image N]: <description>` text parts in
|
||
their place. A failed describe yields `null` and the original image part is
|
||
**preserved** (#4012) — except on the combo describe path when every
|
||
describe failed, where a confirmed non-vision upstream gets an
|
||
`(unavailable — no vision-capable provider connected)` stub instead (#8430).
|
||
6. Return `modifiedPayload` + meta (`imagesProcessed`, `descriptions`,
|
||
`processingTimeMs`, `visionModel`).
|
||
|
||
#### Mode selector (`modalityBridgeVisionMode`)
|
||
|
||
| Mode | Default | Behavior |
|
||
| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `auto` | ✔ | Legacy heuristic, untouched (#6640/#7204): non-combo/`auto/` models reroute to the best vision model unless the original model already has usable credentials (then describe); combo targets always describe. |
|
||
| `describe` | | Always describe — the reroute block is skipped entirely; the user's chosen model always answers. |
|
||
| `reroute` | | Force reroute: the keep-credentialed-model guard is bypassed. The reroute-**target** credential guard still applies — when no usable vision target exists, the request falls through to describe so raw images never reach a text-only backend (#8430). |
|
||
|
||
Forced modes short-circuit **before** the auto heuristic runs; `auto` behavior
|
||
is byte-identical to the pre-PR-1 guardrail.
|
||
|
||
#### Task-aware describe prompt (`modalityBridgeVisionTaskAware`)
|
||
|
||
Default **true**. `composeVisionPrompt()` (`visionBridgeHelpers.ts`) appends
|
||
the text of the **last user message** (truncated to 500 chars) to the base
|
||
describe prompt, steering the description toward what the user actually asked
|
||
(codex-vision-proxy pattern) and asking the vision model to transcribe visible
|
||
text. With the flag off — or no user text — the base prompt is used unchanged.
|
||
|
||
#### Describe output cap (`modalityBridgeVisionMaxChars`)
|
||
|
||
| Key | Default | Range |
|
||
| ------------------------------ | ------- | ---------------- |
|
||
| `modalityBridgeVisionMaxChars` | `0` | `0` or 100–50000 |
|
||
|
||
`0` (default) means **no cap** — the description returned by
|
||
`callVisionModel()` is passed through unmodified, preserving the existing
|
||
behavior. Any value in the 100–50000 range truncates the description with a
|
||
`…` suffix before it is spliced back as `[Image N]: <description>`
|
||
(`VisionBridgeGuardrail.preCall()` in `src/lib/guardrails/visionBridge.ts`).
|
||
Raise this for detail-heavy OCR tasks where the downstream model needs the
|
||
full transcription; lower it to bound token usage on chatty vision models.
|
||
The dashboard field lives on the Vision tab's Advanced panel
|
||
(`modality-bridge-max-chars` in `ModalityBridgeVisionTab.tsx`) and clamps any
|
||
value between 1 and 99 up to the 100 floor while leaving an explicit `0`
|
||
untouched — `0` is a valid Zod value in its own right
|
||
(`z.union([z.literal(0), z.number().int().min(100).max(50000)])`), not merely
|
||
the "unset" default.
|
||
|
||
#### Describe cache (`modalityBridge/bridgeCache.ts`)
|
||
|
||
In-memory LRU + TTL cache for describe outputs, shared process-wide.
|
||
Key = `sha256(imageRef + composedPrompt + configuredBridgeModel)` with
|
||
length-prefix framing (no field-boundary collisions). The model component is
|
||
the **configured** bridge model, not the model that actually answered —
|
||
`callVisionModel` may fall back internally, and keying per attempt would
|
||
fragment the cache. Failed describes are never cached. Settings:
|
||
|
||
| Key | Default | Range |
|
||
| ------------------------------- | ------- | ------- |
|
||
| `modalityBridgeCacheEnabled` | `true` | — |
|
||
| `modalityBridgeCacheTtlMinutes` | `60` | 1–1440 |
|
||
| `modalityBridgeCacheMaxEntries` | `200` | 10–5000 |
|
||
|
||
#### Remote image normalization (self-loop describe/base64 fetch)
|
||
|
||
When the bridge fetches a **remote** image itself — the Anthropic describe
|
||
self-call and the claude-wire-format base64 conversion
|
||
(`ensureBase64ImagesForClaudeWire`), both via
|
||
`fetchRemoteImageAsDataUri()` in `visionBridgeHelpers.ts` — the resulting data
|
||
URI is passed through `normalizeDataUri()`
|
||
(`open-sse/utils/imageNormalize.ts`) before being embedded in the vision-model
|
||
request. Oversized images are downscaled to a **2048px long edge** (matching
|
||
the resize cap OpenAI/Anthropic already apply server-side), which cuts
|
||
upload bytes/latency without changing what the vision model sees. Resizing
|
||
uses `sharp`, loaded via dynamic import: on a platform where its native
|
||
binary fails to load, `normalizeDataUri()` **never throws** — it falls back
|
||
to a passthrough of the original bytes, so the describe/base64-conversion
|
||
path always keeps working. Non-image bytes (a fetch that did not return a
|
||
decodable image) are also passed through untouched. This normalization is
|
||
scoped to images the bridge fetches for its own self-call — it is never
|
||
applied to the caller's raw passthrough payload, consistent with the
|
||
opt-in-only mutation principle (Hard Rule #20).
|
||
|
||
#### Settings schema + migration
|
||
|
||
The new `modalityBridge*` keys are Zod-validated in `updateSettingsSchema`
|
||
(`src/shared/validation/settingsSchemas.ts`): `modalityBridgeVisionEnabled`,
|
||
`modalityBridgeVisionMode`, `modalityBridgeVisionModel`,
|
||
`modalityBridgeVisionTaskAware`, `modalityBridgeVisionPrompt`,
|
||
`modalityBridgeVisionTimeout`, `modalityBridgeVisionMaxImages`,
|
||
`modalityBridgeVisionMaxChars`, the `modalityBridgeCache*` trio, and the
|
||
`modalityBridgeAudio*` group used by the Audio Bridge. Migration
|
||
`141_modality_bridge_settings.sql` copies existing legacy
|
||
`visionBridge*` values to the matching new keys (idempotent, never overwrites
|
||
an operator-set `modalityBridge*` value); the legacy keys stay accepted as a
|
||
read fallback for one release cycle.
|
||
|
||
#### Transparency header + stats
|
||
|
||
Describe-transformed responses carry
|
||
`x-omniroute-modality-bridge: image->text;model=<visionModel>;parts=<n>`
|
||
(built by `buildModalityBridgeHeader()` in `modalityBridge/bridgeStats.ts`,
|
||
stamped by `withModalityBridgeHeader()` in `src/sse/handlers/chatHelpers.ts`).
|
||
Rerouted requests get **no** header — the payload was untouched and the model
|
||
swap is already visible in the response body's `model` field.
|
||
|
||
`GET /api/modality-bridge/stats` (management auth, same tier as
|
||
`GET /api/settings`) returns the in-memory per-modality counters
|
||
`{ attempts, successes, bridged, cacheHits, failures, totalLatencyMs,
|
||
latencySamples, averageLatencyMs, lastUsedAt }` for `vision`, `audio`, and
|
||
`video`. `averageLatencyMs` uses `latencySamples`, not all attempts, as its
|
||
denominator; an operation without timing does not fabricate a zero-millisecond
|
||
sample. `bridged` remains the backward-compatible alias for successful
|
||
conversions; failed attempts do not increment it.
|
||
Counters reset on process restart by design
|
||
(telemetry, not accounting).
|
||
|
||
#### Dashboard configuration
|
||
|
||
The dedicated dashboard page is
|
||
`/dashboard/settings/modality-bridge`. Its URL-addressable `Vision`, `Audio`,
|
||
and `Video` tabs preserve query parameters while switching the `tab` value.
|
||
The Vision tab exposes enablement, mode, model selection (including the automatic
|
||
default), task-aware prompting, advanced timeout/image/description-length/cache
|
||
limits, runtime
|
||
counters, and a guarded sample request. The Audio tab is also live: it exposes
|
||
enablement, an STT-only model picker with Auto, timeout/max-clip limits, audio
|
||
counters, and an `input_audio` sample test. The Video tab is functional: it reports
|
||
the FFmpeg/ffprobe runtime state, persists enable/model/frame/video/timeout limits,
|
||
filters the model picker to vision-capable models, and exposes video counters.
|
||
|
||
The former Vision Bridge card under AI settings is a compatibility link to the
|
||
new page; it no longer owns a second copy of the form. Media Providers also
|
||
links Image-to-Text and Speech-to-Text workflows to the corresponding Modality
|
||
Bridge tabs without removing the existing Speech-to-Text playground.
|
||
|
||
**Self-loop admission bypass:** when the describe call routes through OmniRoute's
|
||
own `/v1` self-loop (non-standard provider model), the sub-request sends
|
||
`x-omniroute-admission-bypass: internal` and is authenticated with the resolved
|
||
self-loop credential — the local `sk_omniroute` sentinel in local mode, or the
|
||
operator-configured `OMNIROUTE_API_KEY` / `ROUTER_API_KEY` env key (#1350) so
|
||
`REQUIRE_API_KEY=true` deployments can still run the describe call. The bypass
|
||
is only honored for those exact credentials, so external clients cannot use the
|
||
header to skip admission.
|
||
|
||
Legacy defaults live in `src/shared/constants/visionBridgeDefaults.ts`; the
|
||
new mode/task-aware/cache defaults and the settings resolver live in
|
||
`src/shared/constants/modalityBridgeDefaults.ts`. The guardrail exposes a
|
||
`deps` constructor option so tests can inject fake `getSettings` and
|
||
`callVisionModel` implementations.
|
||
|
||
### Audio Bridge (`audioBridge.ts`) — Modality Bridge PR-3
|
||
|
||
Intercepts audio-bearing chat requests before they reach a target that is not
|
||
known to accept audio input. It never reroutes the chat request: audio parts are
|
||
transcribed through the existing OpenAI-compatible multipart endpoint and the
|
||
chosen chat model continues with text transcripts.
|
||
|
||
Flow:
|
||
|
||
1. Resolve `supportsAudio` through `getResolvedModelCapabilities()`. Explicit
|
||
provider-registry metadata wins, then static model metadata, then synced
|
||
`modalities_input`. A declared input list without `audio` is `false`; no
|
||
capability evidence remains `null`. Both `false` and `null` activate the
|
||
conservative bridge, while `true` bypasses it.
|
||
2. Resolve `modalityBridgeAudio*` settings and extract spliceable top-level
|
||
audio parts from every message through the shared `detectMediaParts()`
|
||
detector. Supported wire shapes are OpenAI `input_audio`, `audio_url`, and
|
||
`source.media_type: "audio/*"`. Nested audio is detected for routing but not
|
||
removed by the splice path. Work is capped by `modalityBridgeAudioMaxClips`;
|
||
later parts stay untouched.
|
||
3. Honor a configured `provider/model`, or let `selectAudioBridgeModel()` walk
|
||
`AUDIO_TRANSCRIPTION_PROVIDERS` in stable catalog order and select the first
|
||
model with a usable active provider credential.
|
||
4. `callAudioTranscription()` converts base64/data-URI audio to a multipart
|
||
`file`, or downloads a remote `audio_url` through the public-only outbound
|
||
guard with DNS pinning and a 25 MB bound. It then POSTs the file and selected
|
||
model to the local `/v1/audio/transcriptions` self-loop, authenticated with
|
||
`resolveSelfLoopBearer()`. The existing transcription route performs normal
|
||
credential lookup, cooldown/rate-limit handling, and provider dispatch.
|
||
5. Successful calls replace their parts with `[Audio N]: <transcript>`. Calls
|
||
run with `Promise.allSettled`: an individual failure preserves that original
|
||
audio part (#4012 contract). If every call fails and the target is proven
|
||
`supportsAudio === false`, the parts become
|
||
`[Audio N]: (unavailable — no STT provider connected)` (#8430 contract). For
|
||
an unknown target (`null`), an all-failure result stays untouched. A proven
|
||
text-only target with no usable STT credential receives the same explicit
|
||
stub without issuing a network call.
|
||
|
||
Successful transcripts use the process-wide Modality Bridge LRU/TTL cache. The
|
||
key combines the audio reference, the stable `audio-transcription` operation
|
||
label, and selected STT model; failures are never cached. Audio attempts update
|
||
the shared `bridged`, `cacheHits`, `failures`, and `lastUsedAt` counters.
|
||
Transformed responses carry
|
||
`x-omniroute-modality-bridge: audio->text;model=<sttModel>;parts=<n>`; untouched
|
||
requests do not receive an Audio Bridge segment.
|
||
|
||
Runtime settings are DB-backed and Zod-validated:
|
||
|
||
| Key | Default | Range |
|
||
| ----------------------------- | ------- | -------------- |
|
||
| `modalityBridgeAudioEnabled` | `true` | — |
|
||
| `modalityBridgeAudioModel` | `""` | Auto or STT ID |
|
||
| `modalityBridgeAudioTimeout` | `60000` | 1000–300000 |
|
||
| `modalityBridgeAudioMaxClips` | `3` | 1–10 |
|
||
|
||
The shared cache remains controlled by `modalityBridgeCacheEnabled`,
|
||
`modalityBridgeCacheTtlMinutes`, and `modalityBridgeCacheMaxEntries`.
|
||
|
||
### Video Bridge (`videoBridge.ts`)
|
||
|
||
Intercepts top-level video parts in Chat Completions `messages` and Responses
|
||
API `input` before a target without known native video support is called.
|
||
Supported shapes are `input_video`, `video_url`, `video_source`, HTTPS URLs,
|
||
and `data:video/*;base64,...` data URIs. Plain filenames in text are not treated
|
||
as video.
|
||
|
||
The public `/v1` request path never imports or invokes a subprocess. Remote
|
||
videos are downloaded under a 50 MiB bound; inline base64 videos have a
|
||
conservative 36 MiB decoded per-video cap so the model/messages/framing envelope
|
||
can remain inside the public JSON request admission limit of 50 MiB. Inline
|
||
length and decoded-size estimates are checked before allocation. HTTPS is
|
||
required on the initial remote URL and every redirect, using the existing
|
||
public-only outbound guard with DNS pinning. The bytes then cross the exact internal
|
||
`POST /api/modality-bridge/video/extract` broker boundary. That route is both
|
||
`LOCAL_ONLY` and `SPAWN_CAPABLE`, accepts only a per-process authenticated,
|
||
trusted-loopback request, and never accepts a URL, filesystem path, executable,
|
||
or argument list. The API body-size pipeline and the handler's incremental body
|
||
reader independently enforce a 50 MiB broker input cap. Its bounded queue runs
|
||
one extraction at a time, allows four pending jobs, and caps pending input at
|
||
100 MiB.
|
||
|
||
Inside the broker, `ffprobe` reads a private local file; the fixed format
|
||
allowlist excludes playlist and manifest formats. For allowed MOV-family
|
||
containers, external MOV data references remain disabled by default, and the
|
||
fixed command does not opt in to them. Both `ffprobe` and `ffmpeg` use the
|
||
`file`-only protocol whitelist, one thread, fixed argument arrays, no shell,
|
||
and executables resolved from `PATH`. Attached-picture cover streams are not
|
||
playable candidates. All playable streams must satisfy the limits, and an
|
||
explicit default stream is preferred before the deterministic lowest-index
|
||
fallback. Videos are limited to 600 seconds, 8,192 pixels per dimension, and
|
||
33,554,432 source pixels. FFmpeg samples 1–16 midpoint JPEG frames, scales down
|
||
the long edge to at most 1,024 pixels without upscaling smaller inputs, and
|
||
never receives a URL.
|
||
Each frame is limited to 4 MiB, all raw frames together to 23 MiB, and the
|
||
serialized broker response to 32 MiB. A private temporary directory is removed
|
||
in `finally`. OmniRoute does not bundle FFmpeg and does not accept a custom
|
||
executable path.
|
||
|
||
Frames are captioned sequentially with the configured Video model. An empty
|
||
Video override inherits the Vision setting; if both are empty, the Vision
|
||
auto-router selects the effective vision-capable model. Successful captions
|
||
replace the original part with a stable `[Video description:` prefix that also
|
||
marks the text as an untrusted media-derived observation and tells downstream
|
||
models not to follow instructions found in the media. Frame-caption cache keys
|
||
include the JPEG bytes, prompt, timestamp, and effective model; only successful
|
||
captions are cached. Cache entries retain the actual successful producer model,
|
||
including a fallback model; the bridge reports `mixed` when different frames
|
||
were produced by different models. A cache hit reuses that producer identity
|
||
instead of relabeling it as the requested routing plan.
|
||
|
||
The guardrail extracts every supported video part but describes no more than
|
||
`modalityBridgeVideoMaxVideos`. For a target proven to have
|
||
`supportsVideo === false`, failed and over-limit videos become explicit safe
|
||
text markers so no raw video survives. When capability is unknown, those parts
|
||
remain untouched. Targets with `supportsVideo === true` bypass the bridge.
|
||
The client request abort signal propagates through download, broker queue,
|
||
subprocesses, and caption calls; aborts stop between videos and never fail open
|
||
to raw media.
|
||
|
||
Runtime settings are DB-backed and Zod-validated:
|
||
|
||
| Key | Default | Range / behavior |
|
||
| ------------------------------- | -------- | ------------------------------- |
|
||
| `modalityBridgeVideoEnabled` | `false` | Optional runtime, opt-in |
|
||
| `modalityBridgeVideoModel` | `""` | Inherit the Vision Bridge model |
|
||
| `modalityBridgeVideoFrameCount` | `8` | 1–16 |
|
||
| `modalityBridgeVideoMaxVideos` | `1` | 1–4 |
|
||
| `modalityBridgeVideoTimeout` | `120000` | 1000–120000 ms |
|
||
|
||
Legacy persisted Video timeout values above 120 seconds are clamped to the
|
||
broker deadline; new settings writes above that limit are rejected.
|
||
`GET /api/modality-bridge/video/runtime` requires trusted stamped loopback
|
||
locality before authentication or runtime probing, then requires management
|
||
auth. It returns only `available`, sanitized FFmpeg/ffprobe versions, and a fixed
|
||
reason when the runtime is unavailable. The internal extraction endpoint is not
|
||
a public upload API: queue saturation returns `503` plus `Retry-After`, a caller
|
||
disconnect returns `499`, and the fixed broker deadline returns `504`. Converted responses add
|
||
`video->text;model=<visionModel>;parts=<videos>` to the central
|
||
`x-omniroute-modality-bridge` header without removing Vision or Audio segments.
|
||
|
||
### PII Masker (`piiMasker.ts`)
|
||
|
||
Runs on **both** stages.
|
||
|
||
- **`preCall`** clones the payload, walks `system`, `messages`, `input`, and
|
||
`prompt` (including plain string items), and applies `processPII()` (from
|
||
`@/shared/utils/inputSanitizer`) to string `content`/`text` fields. When
|
||
`PII_REDACTION_ENABLED=true`, detected PII is redacted in the outbound
|
||
payload. This is independent of `INPUT_SANITIZER_MODE` (which only controls
|
||
prompt-injection policy). When redaction is off, the call records detection
|
||
counts without rewriting content.
|
||
- **`postCall`** deep-clones the response, runs `sanitizePIIResponse()` plus
|
||
the Responses-API-shape masker (`maskResponsesOutput` — covers
|
||
`output_text` and `output[].content[].text`). If any redaction occurs, the
|
||
modified response replaces the original.
|
||
|
||
The guardrail never blocks; it only annotates (`meta.detections`,
|
||
`meta.redacted`) or rewrites.
|
||
|
||
### Prompt Injection (`promptInjection.ts`)
|
||
|
||
Detects adversarial structures in user-supplied content and enforces the
|
||
configured policy. Behavior is driven by environment variables and constructor
|
||
options:
|
||
|
||
| Setting | Env var | Default | Effect |
|
||
| --------------- | ----------------------------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| Enabled | `INPUT_SANITIZER_ENABLED` | `true` | When `false`, guardrail short-circuits. |
|
||
| Mode | `INJECTION_GUARD_MODE` / `INPUT_SANITIZER_MODE` | `warn` | Injection policy: `block`, `warn`, or `log`. (`redact` is accepted for back-compat but does **not** strip injection text; request PII rewrite is controlled by `PII_REDACTION_ENABLED`.) |
|
||
| Block threshold | `blockThreshold` option / `INPUT_SANITIZER_BLOCK_THRESHOLD` (alias `INJECTION_GUARD_BLOCK_THRESHOLD`) | `high` | Minimum severity required to block. Medium is observe-only at default. |
|
||
|
||
**Mode precedence** (`getMode`): caller `options.mode` →
|
||
`INJECTION_GUARD_MODE` **DB feature-flag override** (Dashboard → Settings →
|
||
Feature Flags) → `INJECTION_GUARD_MODE` env → `INPUT_SANITIZER_MODE` env →
|
||
`warn`. A dashboard override therefore wins over the env vars, so the Feature
|
||
Flags UI controls the running guard live (no restart). The DB read is fail-safe:
|
||
if it errors, the guard falls back to the env-based behavior, and when no
|
||
override is set behavior is identical to env-only resolution.
|
||
|
||
Detection sources:
|
||
|
||
1. `sanitizeRequest()` from `@/shared/utils/inputSanitizer` (shared detector
|
||
set used elsewhere in the pipeline).
|
||
2. Built-in `DEFAULT_GUARD_PATTERNS` (currently `system_override_inline` and
|
||
`markdown_system_block`, both `high` severity).
|
||
3. Optional `customPatterns` passed via constructor options (strings, regex,
|
||
or `{ name, pattern, severity }` records).
|
||
|
||
When `mode === "block"` **and** at least one detection meets the severity
|
||
threshold, `preCall` returns `{ block: true, message: "Request rejected:
|
||
suspicious content detected" }`. In `warn`/`log` modes the guardrail logs but
|
||
allows the call. The shared helper `evaluatePromptInjection()` is also exported
|
||
for callers that need to evaluate prompts without going through the registry.
|
||
|
||
**Scan bound (v3.8.20):** the detector only inspects the **first 16 KB** of
|
||
joined prompt text — `MAX_INJECTION_SCAN_BYTES = 16 * 1024` (16 384 bytes) in
|
||
`src/shared/utils/inputSanitizer.ts`. Both `detectInjection()` and
|
||
`evaluatePromptInjection()` `slice(0, MAX_INJECTION_SCAN_BYTES)` before running
|
||
the pattern loop. Injection directives sit near the top of an input, so this
|
||
caps regex CPU/GC on multi-hundred-KB payloads without weakening detection (cf.
|
||
#3932, #4041).
|
||
|
||
### Credential Masker (`credentialMasker.ts`)
|
||
|
||
Runs on **both** stages, last in the default chain (priority `95`). Redacts
|
||
well-known API-key / secret-token patterns from the outbound payload (message
|
||
content, tool-call arguments, tool results) **and** the provider response, so a
|
||
credential pasted into a prompt (or echoed back by a tool result) is not leaked
|
||
to the upstream provider or back to the client.
|
||
|
||
- **Opt-in only**, same convention as PII redaction (Hard Rule #20-adjacent):
|
||
disabled unless `settings.credentialRedactionEnabled === true` **or**
|
||
`CREDENTIAL_REDACTION_ENABLED=true`. With it off, the guardrail is a no-op —
|
||
it never blocks and never rewrites.
|
||
- `redactCredentials()` walks the full payload/response tree (`walkValue()`,
|
||
prototype-pollution-safe, cycle-safe via `WeakSet`) and replaces matches with
|
||
a `[REDACTED:<type>]` placeholder, cloning only the branches that actually
|
||
changed.
|
||
- `CREDENTIAL_PATTERNS` covers LLM provider keys (OpenAI, OpenAI-proj,
|
||
Anthropic, Google, Hugging Face, Replicate), VCS/SaaS tokens (GitHub, Slack,
|
||
Linear, Notion, npm, Postman, Discord), payment keys (Stripe, Square), cloud
|
||
keys (AWS access key, Twilio, SendGrid, Mailgun), private keys / JWTs,
|
||
credential-bearing connection strings (`mongodb://user:pass@...`, etc.), and
|
||
a generic `Authorization`/`x-api-key`/`api-key`/`apikey` header-value
|
||
pattern. Header-shaped keys (`authorization`, `x-api-key`, `api-key`,
|
||
`apikey`) are redacted structurally (value only, scheme prefix like
|
||
`Bearer `/`Basic ` preserved) rather than via the generic text regex.
|
||
- The guardrail never blocks; it only rewrites (`modifiedPayload` /
|
||
`modifiedResponse`) and annotates (`meta.credentialsRedacted`, `meta.count`).
|
||
|
||
Regression guard: `tests/unit/credential-masker-guardrail.test.ts`.
|
||
|
||
## Base Contract (`base.ts`)
|
||
|
||
```typescript
|
||
class BaseGuardrail {
|
||
enabled: boolean;
|
||
name: string;
|
||
priority: number;
|
||
|
||
constructor(name: string, options?: { enabled?: boolean; priority?: number });
|
||
|
||
async preCall(payload: unknown, context: GuardrailContext): Promise<GuardrailResult | void>;
|
||
|
||
async postCall(response: unknown, context: GuardrailContext): Promise<GuardrailResult | void>;
|
||
}
|
||
|
||
interface GuardrailResult<TValue = unknown> {
|
||
block?: boolean; // true short-circuits the chain
|
||
message?: string; // surfaced when blocking
|
||
meta?: Record<string, unknown> | null;
|
||
modifiedPayload?: TValue; // returned by preCall to rewrite the request
|
||
modifiedResponse?: TValue; // returned by postCall to rewrite the response
|
||
}
|
||
|
||
interface GuardrailContext {
|
||
apiKeyInfo?: Record<string, unknown> | null;
|
||
disabledGuardrails?: string[] | null;
|
||
endpoint?: string | null;
|
||
headers?: Headers | Record<string, unknown> | null;
|
||
log?: GuardrailLog | Console | null;
|
||
method?: string | null;
|
||
model?: string | null;
|
||
provider?: string | null;
|
||
signal?: AbortSignal;
|
||
sourceFormat?: string | null;
|
||
stream?: boolean;
|
||
targetFormat?: string | null;
|
||
}
|
||
```
|
||
|
||
A guardrail signals "no change" by returning either `void`, `{}`, or
|
||
`{ block: false }`. Returning a `modifiedPayload`/`modifiedResponse` replaces
|
||
the value flowing through the chain for downstream guardrails.
|
||
`signal?: AbortSignal` carries the caller lifecycle into guardrails. A request abort is the deliberate fail-open exception: media bridges stop work and cleanup without restoring raw media to a target known not to support it.
|
||
|
||
## Registry (`registry.ts`)
|
||
|
||
The singleton `guardrailRegistry` exposes:
|
||
|
||
- `register(guardrail)` — adds (or replaces by normalized name) a guardrail and
|
||
re-sorts by ascending `priority`.
|
||
- `clear()` / `list()` — administrative helpers.
|
||
- `runPreCallHooks(payload, context)` — iterates active guardrails, threads the
|
||
payload through `modifiedPayload`, and stops on the first `block: true`.
|
||
- `runPostCallHooks(response, context)` — same flow on the response side.
|
||
- `resetGuardrailsForTests({ registerDefaults })` — clears state and optionally
|
||
re-registers the defaults for clean test isolation.
|
||
|
||
Both runners return `{ blocked, payload|response, results, guardrail?, message? }`
|
||
where `results` is an array of `GuardrailExecutionResult` records that include
|
||
per-guardrail `blocked`, `skipped`, `modified`, `error`, and `meta` fields,
|
||
useful for tracing.
|
||
|
||
### Disabling Guardrails Per-Request
|
||
|
||
`resolveDisabledGuardrails({ apiKeyInfo, body, headers })` aggregates a
|
||
de-duplicated list of guardrail names that should be skipped for the current
|
||
request. Sources (all optional, all merged):
|
||
|
||
- `apiKeyInfo.disabledGuardrails`
|
||
- Request body `disabledGuardrails` (top-level)
|
||
- Request body `metadata.disabledGuardrails`
|
||
- Header `x-omniroute-disabled-guardrails` (or legacy
|
||
`x-disabled-guardrails`)
|
||
|
||
Values may be arrays of strings or a comma-separated string; names are
|
||
normalized to lowercase kebab-case (`pii_masker` → `pii-masker`). The result
|
||
is passed through `context.disabledGuardrails` to the registry, which skips
|
||
matching guardrails (`skipped: true` in `results`).
|
||
|
||
## Execution Order
|
||
|
||
For each request flowing through `src/sse/handlers/chat.ts` and
|
||
`open-sse/handlers/chatCore.ts`:
|
||
|
||
1. `resolveDisabledGuardrails(...)` builds the skip list from API key, body,
|
||
and headers.
|
||
2. `guardrailRegistry.runPreCallHooks(body, ctx)` runs guardrails in ascending
|
||
priority order:
|
||
- Disabled guardrails are recorded as `skipped`.
|
||
- Each guardrail's `preCall` may rewrite the payload via `modifiedPayload`.
|
||
- The first `block: true` short-circuits the chain and the handler returns
|
||
a guardrail rejection response.
|
||
3. The (potentially rewritten) payload flows into combo routing and upstream
|
||
dispatch.
|
||
4. After the response is assembled, `guardrailRegistry.runPostCallHooks(...)`
|
||
runs the same chain on the response. `block: true` here drops the upstream
|
||
response.
|
||
|
||
Guardrails that throw are recorded with `error: <message>` and logged via
|
||
`logger.warn`, but the chain continues — fail-open by design.
|
||
|
||
## Configuration
|
||
|
||
Environment variables read by the built-in guardrails:
|
||
|
||
| Variable | Used by | Effect |
|
||
| ------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------- |
|
||
| `INPUT_SANITIZER_ENABLED` | `prompt-injection` | Set `false` to disable detection entirely. |
|
||
| `INPUT_SANITIZER_MODE` | `prompt-injection` | Injection policy: `warn`, `block`, or `log`. Legacy value `redact` does not rewrite injection text. |
|
||
| `INJECTION_GUARD_MODE` | `prompt-injection` | Mode for the injection guard; also a DB feature flag that **overrides** the env vars (DB > ENV). |
|
||
| `INPUT_SANITIZER_BLOCK_THRESHOLD` | `prompt-injection` | Minimum severity that `MODE=block` rejects: `high` (default), `medium`, or `low`. |
|
||
| `INJECTION_GUARD_BLOCK_THRESHOLD` | `prompt-injection` | Legacy alias for `INPUT_SANITIZER_BLOCK_THRESHOLD`. |
|
||
| `PII_REDACTION_ENABLED` | `pii-masker` | When `true`, request PII is redacted (independent of injection mode). |
|
||
| `PII_RESPONSE_SANITIZATION` / `_MODE` | `pii-masker` (downstream) | Controls response-side masker behavior. |
|
||
|
||
The Modality Bridge guardrails read runtime config from the DB-backed settings
|
||
store (`getSettings()`), not env vars. Vision's primary keys are
|
||
`modalityBridgeVisionEnabled`, `modalityBridgeVisionMode`,
|
||
`modalityBridgeVisionModel`, `modalityBridgeVisionTaskAware`,
|
||
`modalityBridgeVisionPrompt`, `modalityBridgeVisionTimeout`,
|
||
`modalityBridgeVisionMaxImages`, `modalityBridgeVisionMaxChars`,
|
||
`modalityBridgeCacheEnabled`, `modalityBridgeCacheTtlMinutes`, and
|
||
`modalityBridgeCacheMaxEntries`. The legacy
|
||
`visionBridge*` keys are accepted only as the documented one-cycle read
|
||
fallback; dashboard writes use the primary keys. Defaults and the fallback
|
||
resolver live in `src/shared/constants/modalityBridgeDefaults.ts`, with legacy
|
||
constants retained in `src/shared/constants/visionBridgeDefaults.ts`.
|
||
|
||
Audio uses `modalityBridgeAudioEnabled`, `modalityBridgeAudioModel`,
|
||
`modalityBridgeAudioTimeout`, and `modalityBridgeAudioMaxClips`, plus the shared
|
||
`modalityBridgeCache*` settings. Audio has no legacy-key fallback because these
|
||
keys were introduced with the Modality Bridge schema.
|
||
|
||
Video uses `modalityBridgeVideoEnabled`, `modalityBridgeVideoModel`,
|
||
`modalityBridgeVideoFrameCount`, `modalityBridgeVideoMaxVideos`, and
|
||
`modalityBridgeVideoTimeout`, plus the shared `modalityBridgeCache*` settings.
|
||
It is disabled by default because FFmpeg/ffprobe are optional operational
|
||
dependencies and frame captioning adds latency and model cost.
|
||
|
||
## Custom Guardrails
|
||
|
||
```typescript
|
||
import { BaseGuardrail, guardrailRegistry } from "@/lib/guardrails";
|
||
|
||
class BudgetGuardrail extends BaseGuardrail {
|
||
constructor() {
|
||
super("budget", { priority: 50 });
|
||
}
|
||
|
||
async preCall(payload, ctx) {
|
||
if (ctx.apiKeyInfo?.budgetExceeded) {
|
||
return { block: true, message: "Daily budget exceeded" };
|
||
}
|
||
return { block: false };
|
||
}
|
||
}
|
||
|
||
guardrailRegistry.register(new BudgetGuardrail());
|
||
```
|
||
|
||
Steps:
|
||
|
||
1. Create `src/lib/guardrails/myGuardrail.ts` extending `BaseGuardrail`.
|
||
2. Implement `preCall` and/or `postCall`.
|
||
3. Either register at import time (push from `registerDefaultGuardrails`) or
|
||
call `guardrailRegistry.register(...)` at runtime — the registry replaces
|
||
any prior guardrail with the same normalized name.
|
||
4. Add tests under `tests/unit/` (existing examples:
|
||
`tests/unit/guardrails-registry.test.ts`,
|
||
`tests/unit/prompt-injection-guard.test.ts`,
|
||
`tests/unit/guardrails/visionBridge.test.ts`).
|
||
|
||
## Testing
|
||
|
||
Use `resetGuardrailsForTests()` between tests to start from a known state.
|
||
Pass `{ registerDefaults: false }` to start with an empty registry and
|
||
register only the guardrails under test. Vision Bridge accepts dependency
|
||
injection (`deps.getSettings`, `deps.callVisionModel`); Audio Bridge exposes the
|
||
equivalent seams for settings, capabilities, STT model selection, credential
|
||
checks, and transcription. Tests can therefore exercise both flows without DB
|
||
or network access.
|
||
|
||
## See Also
|
||
|
||
- `src/lib/guardrails/` — implementation
|
||
- `src/shared/utils/inputSanitizer.ts` — shared detector that powers
|
||
prompt-injection and PII masking
|
||
- `src/shared/constants/visionBridgeDefaults.ts` — Vision Bridge defaults and
|
||
forced-bridge model list
|
||
- `src/shared/constants/modalityBridgeDefaults.ts` — shared Vision/Audio runtime defaults
|
||
- `docs/architecture/RESILIENCE_GUIDE.md` — orthogonal layer (circuit breaker, cooldowns)
|
||
- `docs/reference/ENVIRONMENT.md` — full env var reference
|
||
|
||
## Injection-guard route coverage & red-team (Phase 8 · Block D)
|
||
|
||
The injection-guard (`createInjectionGuard` / `withInjectionGuard`) covers all routes
|
||
that accept user prompts. It respects `INJECTION_GUARD_MODE` (default `warn` = log only;
|
||
`block` = returns HTTP 400 `SECURITY_001`).
|
||
|
||
| Type | Routes | Default mode |
|
||
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
|
||
| Text (existing) | `/v1/chat/completions`, `/v1/completions`, `/v1/relay/chat/completions` | warn |
|
||
| Generative | `/v1/messages`, `/v1/responses`, `/v1/images/generations`, `/v1/images/edits`, `/v1/videos/generations`, `/v1/music/generations`, `/v1/audio/speech` | warn |
|
||
| Data | `/v1/embeddings`, `/v1/rerank`, `/v1/search`, `/v1/moderations` | warn |
|
||
|
||
Text extraction (`extractMessageContents`) covers `messages`/`input`/`prompt`/`query`+`documents`/`instructions`/`system`.
|
||
|
||
**Red-team (nightly, `nightly-llm-security.yml`):** promptfoo validates that each route blocks
|
||
the OWASP-LLM corpus in `INJECTION_GUARD_MODE=block`; garak runs probes (skips without secret).
|
||
`moderations` is included for consistency — operators in block-mode can exempt it via
|
||
`resolveDisabledGuardrails`.
|
||
|
||
The nightly workflow (`.github/workflows/nightly-llm-security.yml`, cron + manual
|
||
dispatch) has two jobs:
|
||
|
||
- **`promptfoo-guard` (blocking)** — runs `promptfoo eval -c promptfooconfig.yaml`
|
||
with `INJECTION_GUARD_MODE=block`. Each adversarial case (e.g. "ignore all
|
||
previous instructions…", DAN-style jailbreaks) asserts the response carries
|
||
`error.code === "SECURITY_001"`, i.e. the guard actually rejected the request.
|
||
- **`garak` (advisory)** — runs garak `--probes promptinject,dan,leakreplay`
|
||
against a local OmniRoute instance (`http://localhost:20128/v1`). Gated on a
|
||
provider secret (`PROMPTFOO_PROVIDER_KEY`); skips gracefully and is suffixed
|
||
`|| true`, so it reports without failing CI.
|
||
|
||
Coverage of the guard helper (`createInjectionGuard` / `withInjectionGuard`)
|
||
spans every prompt-bearing `/v1` route; prompt text is pulled from
|
||
`messages`/`input`/`prompt`/`query`+`documents`/`instructions`/`system` by
|
||
`extractMessageContents()` in `src/shared/utils/inputSanitizer.ts`.
|