HiddenLayer Integration

Add HiddenLayer AIDR as an AI Gateway guardrail to detect prompt injection, PII, and policy violations, and apply your HiddenLayer project’s redaction and blocking rules.

This guide explains how to integrate HiddenLayer AIDR with TrueFoundry to scan LLM prompts, responses, and MCP tool calls for prompt injection, PII, and policy violations.

What is HiddenLayer?

HiddenLayer AISec is a runtime security platform for LLM applications. Detection and enforcement policies are defined in a project in the AISec Platform Console; the AI Gateway sends each guarded request to the HiddenLayer Detection v2 interaction-evaluations API and applies the outcome.

In the TrueFoundry AI Gateway integration, HiddenLayer can run as either a Validate or Mutate guardrail. Validate inspects and can block. Mutate can also apply the redactions that your HiddenLayer project policy returns before the request continues.

Key capabilities

1. Prompt injection and jailbreak detection — Flags adversarial inputs designed to override system instructions.
2. PII detection and redaction — Detects sensitive entities and, in Mutate mode, forwards the redacted text (for example, [REDACTED:US_SSN]) instead of the original.
3. Policy-driven enforcement — Whether HiddenLayer alerts, redacts, or blocks is decided by the project policy you select with Project ID, not by the gateway.
4. MCP tool coverage — The guardrail can also run on MCP tool calls and results.

Redaction only happens when the HiddenLayer project policy is set to redact for the entity. A policy set to alert returns a DETECT outcome with no redaction. HiddenLayer treats PII in assistant messages more strictly than PII in user messages, so response-side redaction can trigger on content that is not redacted on the request side.

Adding HiddenLayer to TrueFoundry

HiddenLayer is a first-class guardrail in the AI Gateway — you configure it through the same form as any other built-in guardrail, no adapter service required.

1. Pick HiddenLayer from the guardrail registry

   From AI Gateway → Guardrails → Registry, select HiddenLayer under External Providers. See Get started with guardrails for the end-to-end flow of adding any guardrail.

2. Create API credentials in HiddenLayer

   In the AISec Platform Console, open the API Keys tab and create an OAuth2 client. Note the client ID and client secret, and the project ID or alias whose policy you want to apply. Keep the secret secure — it grants access to your HiddenLayer detection API.

3. Fill in the HiddenLayer form

   Provide the following fields:

   Field	Required	Description
   Name	✅	Identifier for this guardrail (for example, hiddenlayer). Used when you reference the guardrail from rules.
   Description		Free-form description shown in the dashboard.
   Auth Data → Client ID	✅	HiddenLayer OAuth2 client ID. Stored encrypted.
   Auth Data → Client Secret	✅	HiddenLayer OAuth2 client secret. Stored encrypted. The AI Gateway exchanges it for an access token and caches the token until it expires.
   Project ID	✅	HiddenLayer project ID or alias, sent as HL-Project-Id. Selects the AISec policy applied to each request.
   Region	✅	HiddenLayer region: Us (api.us.hiddenlayer.ai) or Eu (api.eu.hiddenlayer.ai). Choose the region that matches your HiddenLayer tenant.
   Operation	✅	Validate inspects and can block without modifying content (runs in parallel with other validate guardrails). Mutate can validate and also apply HiddenLayer redactions (runs sequentially by priority). Defaults to Validate.
   Priority		Execution order for mutate guardrails. Lower values run first.
   Enforcing Strategy	✅	Enforce blocks on any violation or guardrail error. Enforce But Ignore On Error blocks on violations but lets the request through when HiddenLayer cannot be reached. Audit never blocks — violations are logged only (not available with Mutate).

   The default, Validate, never modifies content: if your HiddenLayer policy redacts an entity, the request is blocked instead. Switch to Mutate when you want the gateway to continue with the redacted content. Use Validate with the Audit strategy to observe DETECT and REDACT outcomes without blocking.

4. Bind the guardrail to models or tools with a rule

   Once the guardrail is saved, attach it through a Guardrail Rule. Use llm_input_guardrails to scan prompts before they reach the model, llm_output_guardrails to scan completions before they’re returned, and the MCP tool hooks to scan tool arguments and results.

   For a step-by-step walkthrough, see Getting Started. For the full policy reference, see Guardrails Configuration.

What is sent to HiddenLayer

• Input guardrails send the user, assistant, and tool messages of the request, each with its own role (tool results use the tool role). System prompts are not sent.
• Output guardrails send the request messages as context followed by the model response. Only the response is ever rewritten.
• MCP tool calls send each tool argument as a user message and the tool result as a single tool message.
• Requester identity is taken from the authenticated TrueFoundry user, not from request headers.

Output guardrails are skipped for streamed responses.

Validation logic

TrueFoundry maps the HiddenLayer outcome.action as follows:

HiddenLayer action	Validate	Mutate
NONE	Allowed. If HiddenLayer returned changed text anyway, it is treated as a redaction (see below).	Allowed. Changed text is applied as a redaction.
DETECT	Violation.	Passed through unchanged.
REDACT	Violation. The payload is never modified.	The redacted text replaces the original prompt, completion, or tool payload.
BLOCK	Violation.	Violation.
Any other action	Passed through.	Passed through.

A violation blocks the request subject to your Enforcing Strategy. A redaction that cannot be applied — for example, HiddenLayer returns a different number of messages than were sent, or the payload cannot be rebuilt — is treated as a violation rather than forwarding the unredacted content.

If the HiddenLayer call fails (authentication error, timeout, 5xx), behavior follows your Enforcing Strategy:

• Enforce — fail closed; the request is blocked.
• Enforce But Ignore On Error — fail open; the request proceeds and the failure is logged.
• Audit — never block; violations and errors are logged only.

Example: Mutate redaction

With Operation: Mutate and a project policy that redacts EMAIL_ADDRESS and US_SSN, this prompt:

My email is [e-mail], SSN 252-36-8938

is forwarded to the model as:

My email is [REDACTED:EMAIL_ADDRESS], SSN [REDACTED:US_SSN]

The same redaction applies to model responses when the guardrail is attached to llm_output_guardrails. The guardrail check in the response shows transformed: true.

Example: blocked request

Error details contain only the action, threat level, rule names, and detected signal and entity types. They never quote the matched content.

Input Guardrail checks failed for integrations: [my-group/hiddenlayer]
- Details: HiddenLayer policy violation
  (action: DETECT; threat level: HIGH; rules: [System] Prompt Injection; signals: prompt_injection)

Under Validate, a redaction is reported the same way:

Input Guardrail checks failed for integrations: [my-group/hiddenlayer]
- Details: HiddenLayer policy violation
  (action: REDACT; threat level: NONE; signals: personally_identifiable_information; entity types: EMAIL_ADDRESS, US_SSN)

You can inspect the full guardrail evaluation in AI Gateway → Monitor → Request Traces.

Supported detections

Exact detector enablement and actions are configured in your HiddenLayer project. Typical coverage includes:

Detection	Description
Prompt injection	Inputs designed to override system instructions or model constraints
PII	Entities such as credit cards, SSNs, phone numbers, IP addresses, and bank numbers, with optional redaction
Code, URLs, language, and denial-of-service checks	Additional analyzers available in the HiddenLayer policy

Migrating from the custom guardrail wrapper

Earlier setups ran the integrations/hiddenlayer FastAPI wrapper behind a Custom Guardrail. The native integration replaces it:

Wrapper	Native guardrail
HIDDENLAYER_CLIENT_ID / HIDDENLAYER_CLIENT_SECRET environment variables	Client ID / Client Secret fields
HIDDENLAYER_PROJECT_ID environment variable	Project ID field
HIDDENLAYER_REGION environment variable	Region field
/validate-input, /validate-output rails	Validate operation
/redact-input, /redact-output rails	Mutate operation
HIDDENLAYER_ALLOW_DETECT_ON_VALIDATE=true	Validate with the Audit enforcing strategy
HIDDENLAYER_FAIL_OPEN_ON_UNAVAILABLE (default: fail open)	Enforcing Strategy — use Enforce But Ignore On Error to keep the previous fail-open default, or Enforce to fail closed

The wrapper failed open on HiddenLayer outages by default. Pick the Enforcing Strategy deliberately: with Enforce But Ignore On Error, traffic passes unscanned while HiddenLayer is unavailable.

After creating the native guardrail, update your guardrail rules or X-TFY-GUARDRAILS selectors to the new <group>/<name> and remove the wrapper’s Custom Guardrail configs and deployment.

Troubleshooting

Ordinary prompts or responses are blocked under Validate

HiddenLayer’s default policy can redact entities such as PERSON, LOCATION, ORGANIZATION, and URL, and flag code or URLs as DETECT. Under Validate, any redaction or DETECT outcome is a violation, so a prompt like “What is the capital of France?” can be blocked because France is a LOCATION. Either narrow the redaction list in your HiddenLayer policy, switch the guardrail to Mutate, or run it with the Audit enforcing strategy.

Prompt injection is not blocked under Mutate

When the HiddenLayer policy lists prompt injection under Detect rather than Block, HiddenLayer returns DETECT. Mutate passes DETECT through unchanged. To stop these requests, add the rule to the policy’s Block list in HiddenLayer, or use a Validate guardrail alongside the Mutate one.

PII is detected but not redacted

Redaction is decided by the HiddenLayer project policy. Confirm the policy for that entity is set to redact rather than alert, that Project ID points at that project, and that the guardrail Operation is Mutate. Under Validate, a redaction is reported as a violation instead of being applied.

Test values such as 123-45-6789 are not flagged

HiddenLayer’s detectors can allow obviously fake values that do not follow real-world structure. Test with realistic values.

Authentication errors (401)

Verify the Client ID and Client Secret, and that the Region matches your HiddenLayer tenant. The gateway refreshes its cached token once on a 401 before reporting the failure.

Requests are blocked with a redaction reason

A redaction_* reason means HiddenLayer returned a redaction that the gateway could not apply safely (for example, a different number of messages than were sent), so the request was blocked instead of forwarded unredacted.

Reference

• HiddenLayer
• TrueFoundry guardrails overview
• Get started with guardrails
• Configure guardrail policies