Configure an External Guardrail

Tasks

Bring your own HTTP classifier — a fine-tuned model, an internal moderation service, anything that accepts text and returns a category — into content-safety scanning alongside the built-in detectors. For how External Guardrails fit into content safety generally, see Content safety policies.

Add a guardrail

1. Go to Settings → Content Safety → External Guardrails and click Add Guardrail to open the Generic HTTP form.

2. Set the Endpoint — must be http or https and must not embed credentials in the URL itself (use Auth below instead). Every scanned prompt, response, and tool call is sent here, so only add an endpoint you trust with that data.

   Saving checks whether the hostname currently resolves to a private address, but this is a best-effort check, not a guarantee — a hostname that doesn't resolve yet (or resolves differently later) can still be saved. The check that actually matters happens on every live scan: each connection re-resolves the endpoint and rejects a private address at that point, regardless of what the save-time check saw.

   If your classifier lives on a private network (an internal moderation service, for example), an operator can allow its specific address via the proxy.ssrfAllowlist config.yaml/Helm setting.

3. Choose Auth — an API key header, a bearer token, or none. A secret you enter is encrypted at rest and never redisplayed; leave it blank when editing to keep the existing one.

4. Configure Response mapping:

   • A required label field and an optional score field — paths into your service's JSON response.
   • An optional label → finding type mapping (for example jailbreak=PROMPT_INJECTION) — maps your vendor's own response labels onto AIControls' finding types. No shared schema needed.
   • An optional list of benign labels (for example benign, safe) for a classifier whose own vocabulary returns an explicit benign value rather than an empty field.

   An unmapped, non-benign label defaults to a generic unsafe-content finding. A response missing the configured label field entirely, or whose score field isn't numeric, is treated as a malformed response, not a benign result — a request-side content finding is only ever raised for CREDENTIAL, PII, PROMPT_INJECTION, or UNSAFE_CONTENT, so mapping a label to anything else is rejected at save time.

5. Click Send test request to confirm the endpoint is reachable and returns something this mapping can parse, before saving. The timeout you configure (100 ms – 30 s) applies to both the live scan path and this test.

   This guardrail's own timeout isn't the only deadline a live scan waits for, though: content.scanTimeoutSeconds (default 5 s) is a shared outer ceiling across every enabled content-safety plugin scanning the same piece of text, and it cancels the whole scan at that point regardless of what any single guardrail is configured to allow. A guardrail saved with a 30 s timeout still only gets 5 s in practice unless an operator also raises content.scanTimeoutSeconds — see Tune the scan timeout.

6. Save. The guardrail is applied immediately on this replica; other replicas pick it up within a short interval.

Request and response contract

Your endpoint must accept POST requests with a JSON body of the shape {"text": "...", "content_type": "..."}, where content_type is one of prompt-input, prompt-output, or tool-args, and reply with 200 OK and a JSON body containing (at minimum) the fields your label/score mapping above points at — for example {"category": "jailbreak", "risk_score": 0.92}.

Built-in entries

Presidio and LlamaGuard (when configured) appear in the same list as built-in entries — their connection settings are configured via config.yaml/Helm, not from this page. From here you can only enable/disable them and send a test request, not adjust their endpoint, auth, or response mapping, and (like any built-in) you can't delete them.

LlamaGuard's entry also shows its fixed category-mapping table — every category, including S10 (Hate), maps to a general unsafe-content finding. LlamaGuard has no prompt-injection category of its own; use the pattern-based and ML classifier detectors for that signal instead.

note

Enabling three or more guardrails shows a latency warning: each runs in parallel, but a slow endpoint still sets the floor for the whole scan's tail latency, and every guardrail is another data-exfiltration surface to account for.