> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://hiddenlayer.com) with TrueFoundry to scan LLM prompts, responses, and MCP tool calls for prompt injection, PII, and policy violations.

## What is HiddenLayer?

[HiddenLayer AISec](https://hiddenlayer.com) 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](https://hiddenlayer.com) 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.

<Note>
  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.
</Note>

## 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.

<Steps>
  <Step title="Pick HiddenLayer from the guardrail registry">
    From **AI Gateway → Guardrails → Registry**, select **HiddenLayer** under **External Providers**. See [Get started with guardrails](/docs/ai-gateway/guardrails-getting-started) for the end-to-end flow of adding any guardrail.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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). |

    <Tip>
      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.
    </Tip>
  </Step>

  <Step title="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](/docs/ai-gateway/guardrails-getting-started). For the full policy reference, see [Guardrails Configuration](/docs/ai-gateway/guardrails-configuration).
  </Step>
</Steps>

## 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.

<Note>
  Output guardrails are skipped for streamed responses.
</Note>

## 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:

```text theme={"dark"}
My email is john@example.com, SSN 252-36-8938
```

is forwarded to the model as:

```text theme={"dark"}
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.

```text theme={"dark"}
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:

```text theme={"dark"}
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](/docs/ai-gateway/custom-guardrails). 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 |

<Warning>
  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.
</Warning>

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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Reference

* [HiddenLayer](https://hiddenlayer.com)
* [TrueFoundry guardrails overview](/docs/ai-gateway/guardrails-overview)
* [Get started with guardrails](/docs/ai-gateway/guardrails-getting-started)
* [Configure guardrail policies](/docs/ai-gateway/guardrails-configuration)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.