Skip to main content
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:
The default, Validate, never modifies content: if your HiddenLayer policy redacts an entity, the request is blocked instead. For most setups, use Mutate and put the rules you want to stop in the Block list of your HiddenLayer policy: HiddenLayer then redacts or blocks, and the gateway applies the outcome. 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 system, user, assistant, and tool messages of the request, each with its own role (tool results use the tool role). System prompts are sent so HiddenLayer can detect tampering, and are never rewritten, even under Mutate.
  • Output guardrails send the request messages (including the system prompt) 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 is the authenticated TrueFoundry user by default, or the fixed Requester ID if you set one. It is never taken from request headers or metadata.
  • Session: when the request carries an x-tfy-conversation-id header, its value is sent as metadata.external_session_id, so HiddenLayer can group the calls of one conversation. Send the same x-tfy-conversation-id on every turn; without it, each call appears as a separate entry in HiddenLayer.
Output guardrails are skipped for streamed responses.

​
Validation logic

TrueFoundry maps the HiddenLayer outcome.action as follows: HiddenLayer automatically replaces content it already redacted in earlier turns of a conversation, and reports NONE when there is nothing new to detect. Validate forwards the original payload unchanged, so it treats that replaced text as a violation rather than passing the original history to the model. For conversations that carry history, use Mutate: it applies HiddenLayer’s returned text, so the model only ever sees the redacted history. 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:
is forwarded to the model as:
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.
Under Validate, a redaction is reported the same way:
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:

​
Migrating from the custom guardrail wrapper

Earlier setups ran the integrations/hiddenlayer FastAPI wrapper behind a Custom Guardrail. The native integration replaces it:
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

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. A blocked request is reported as a violation by the Mutate guardrail.
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.
HiddenLayer’s detectors can allow obviously fake values that do not follow real-world structure. Test with realistic values.
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.
A redaction_* reason means HiddenLayer returned text that the gateway could not safely use, so the request was blocked instead of forwarded unredacted:
  • redaction_returned_under_validate — HiddenLayer returned text that differs from what was sent, usually earlier turns’ redactions in a conversation with history, and Validate cannot apply it. Switch the guardrail to Mutate, which forwards HiddenLayer’s redacted text to the model.
  • redaction_message_count_mismatch — HiddenLayer returned a different number of messages than were sent.
  • redaction_unavailable or redaction_not_applied — HiddenLayer reported a redaction that was missing from its response, or the gateway could not rebuild the request with it.

​
Reference