# Guardrails

Last validated Nov 10, 2026

Guardrails are synchronous hooks that let you inspect, modify, or block LLM traffic at the gateway. A request guardrail acts on a request before Aperture forwards it to the model provider. A response guardrail acts on the provider's response before Aperture returns it to the client. Use guardrails to enforce security policies, scrub PII, restrict tool usage, or stop unsafe tool calls before an agent runs them.

## How guardrails work

A guardrail is an HTTP endpoint you deploy. A matching grant selects the data that Aperture sends to the endpoint. The endpoint returns one of three actions: allow, block, or modify. If you host the endpoint outside your tailnet, the selected data leaves your tailnet when Aperture calls it.

Guardrails use one of three events:

* **`pre_request`**: Fires when Aperture receives a request from a client, before Aperture forwards the request to the upstream provider.
* **`pre_response`**: Fires on every successful response, before Aperture returns it to the client. For a streamed response, Aperture calls the guardrail once per window of text, and the client still receives a stream.
* **`tool_call_pre_response`**: Like `pre_response`, but fires only on responses that contain tool calls. A block from this event blocks the whole response. To drop only some tool calls, use `modify`.

Define the endpoint in the Aperture configuration's [`hooks`][docs-configuration-hooks] section. Then add `send_hooks` with one or more of these events to a grant. The grant selects whose requests trigger the hook and what data the endpoint receives. When a request or response matches the grant, Aperture calls your endpoint and waits for its response before it continues.

## Actions

A guardrail returns one of three actions:

* **Allow**: The request or response proceeds unchanged. Use this when the guardrail inspects the traffic and finds nothing to act on.
* **Block**: Aperture rejects the request or response. By default, the client receives an error response with a status code and message. A blocked request never reaches the provider. A blocked response has already reached Aperture, so the provider call is billed. Use this for hard enforcement, such as rejecting requests that contain PII or violate a policy you define.
* **Modify**: The guardrail returns a replacement. On a request, it replaces the request body, which Aperture forwards to the provider instead of the original. Use this to scrub sensitive data, remove tool declarations, or rewrite content before it reaches the LLM. On a response, it can replace the response text, replace a complete response body, or [edit individual tool calls][docs-configuration-edit-tool-calls]: change a call's arguments, point it at another tool, or remove it. The response's other tool calls go through, so the agent keeps working.

## Hook chains

You can stack multiple guardrails on the same request or response. When multiple guardrails match the same stage, Aperture calls them sequentially:

1. Guardrails run in order of descending `preference` (higher values first), with alphabetical order by hook key as the tiebreak.
2. An `allow` response is a no-op: the chain proceeds to the next guardrail.
3. A `modify` response rewrites the request or response in place. The next guardrail in the chain receives the modified version.
4. A `block` response terminates the chain. No subsequent guardrails run.

## Failure behavior

The `fail_policy` setting on each hook definition controls what happens when Aperture cannot reach a guardrail endpoint or the endpoint returns an error:

* **`fail_open`** (default): The request or response proceeds as if the guardrail returned `allow`. This preserves availability when a guardrail is unhealthy, at the cost of skipping enforcement.
* **`fail_closed`**: Aperture blocks the request or response, by default with an HTTP 503 error. This preserves enforcement at the cost of availability.

Aperture rejects a configuration that sets `fail_policy` to any other value.

Choose `fail_closed` for guardrails where enforcement is mandatory, such as PII scrubbing where you require enforcement. Choose `fail_open` (or accept the default) for guardrails where availability matters more than enforcement, such as content classification.

## Blocks as messages

By default, a block or a `fail_closed` failure returns an error status to the client. Many agents treat an error as temporary and retry the same request, so a blocked request can repeat until the agent gives up. To avoid this, set `block_response` (for blocks) or `fail_response` (for failures) to `"message"` on the hook definition. The client then receives a successful response that contains the guardrail's message as the model's answer, with no tool calls, so the agent shows the message to the user and ends its turn. For details, refer to [block and failure responses][docs-configuration-block-responses].

For the Aperture user, a block sent as a message looks like an ordinary answer from the model. The message is the only sign that a guardrail acted, so write block messages that name the policy and tell the user whom to contact. For example: `Blocked by the Example AI policy: destructive shell command. Ask in #ai-platform.`

A guardrail that edits tool calls is also visible to users: their agent runs a different command than the model proposed, or skips one. Models often notice the change and mention it. For how this looks to users, refer to [requests blocked or changed by a guardrail][docs-troubleshooting-guardrails].

## Guardrails versus integration hooks

Guardrails use the `pre_request`, `pre_response`, and `tool_call_pre_response` events, which are synchronous. Aperture waits for the guardrail response before it forwards the request or returns the response, so the guardrail can block or modify it inline.

Integration hooks such as [Cerbos][docs-integrate-cerbos] and [Oso][docs-integrate-oso] use `entire_request` or `tool_call_entire_request` events. These are asynchronous: Aperture calls the hook in the background after the response completes. Asynchronous hooks cannot block or modify requests. They are designed for observation, authorization decisions, and audit logging.

Zero retention (`duration: "0"`, `require_export: false`) controls stored proxy captures, not the data sent to hooks. Pre-request guardrails still receive the request data that their grants select. Pre-response guardrails still receive the model output, including tool calls, that their grants select. Post-response `entire_request` hooks can still receive the request and response body fields that their grants allow. If you also set `purge: ["captures", "tools"]`, Aperture skips tool extraction, so `tool_call_entire_request` hooks do not fire. Audit hook events and allowed fields separately from capture retention.

If you need to enforce policies before the request reaches the provider, use a guardrail with `pre_request`. If you need to check model output or tool calls before the client receives them, use a guardrail with `pre_response` or `tool_call_pre_response`. If you need to observe completed requests or send data to an external authorization or logging system, use an integration hook with `entire_request` or `tool_call_entire_request`.

## Guardrails and connector traffic

Guardrails fire on LLM requests sent to upstream providers. They do not fire on:

* **Outbound [MCP tool calls][docs-aperture-connectors]**: When an LLM response triggers a tool call to a registered MCP server, Aperture executes the tool call directly. The `pre_request` hook does not intercept this outbound call.
* **HTTP connector proxy requests**: Requests routed through `/v1/connectors/{id}/` bypass the guardrail pipeline entirely.

A guardrail *can* inspect the LLM request that declares available tools (the `tools` array in the request body) and can block or modify that request before it reaches the provider. However, the guardrail does not intercept the subsequent outbound call when the LLM invokes one of those tools.

This distinction matters for security policy: guardrails enforce policy at the LLM provider boundary, not at the MCP or connector boundary. If you need to control which tools are available to an LLM, use [MCP grants][docs-grant-mcp-tool-access] to limit which tools Aperture exposes, rather than relying on guardrails to filter tool declarations from request bodies.

## Next steps

* [Set up a guardrail][docs-set-up-guardrails] to configure a PII-scrubbing guardrail end-to-end.
* [Integrate Highflame with Aperture][docs-integrate-highflame] for an integration that provides both pre-request enforcement and post-response observability through the same endpoint.
* Review the [hooks configuration reference][docs-configuration-hooks] for the full list of hook fields, response formats, tool call edits, streaming behavior, and chain ordering.
* [Reduce Aperture token costs with tsheadroom][docs-reduce-token-costs] for a worked example of a `pre_request` guardrail that compresses bulky LLM request bodies with no client changes.

[docs-aperture-connectors]: /docs/aperture/connectors

[docs-configuration-block-responses]: /docs/aperture/configuration#block-and-failure-responses

[docs-configuration-edit-tool-calls]: /docs/aperture/configuration#edit-tool-calls

[docs-configuration-hooks]: /docs/aperture/configuration#hooks

[docs-grant-mcp-tool-access]: /docs/aperture/how-to/grant-mcp-tool-access

[docs-integrate-cerbos]: /docs/aperture/integrate/cerbos

[docs-integrate-highflame]: /docs/aperture/integrate/highflame

[docs-integrate-oso]: /docs/aperture/integrate/oso

[docs-reduce-token-costs]: /docs/solutions/reduce-aperture-token-costs-with-tsheadroom

[docs-set-up-guardrails]: /docs/aperture/how-to/set-up-guardrails

[docs-troubleshooting-guardrails]: /docs/aperture/troubleshooting#requests-blocked-or-changed-by-a-guardrail
