> This page is for version v0.25.0.
> For other versions, use one of these documentation indexes:
> - Latest (default): https://docs.nvidia.com/nemo/guardrails/latest/llms.txt
> - v0.25.0: https://docs.nvidia.com/nemo/guardrails/v0.25.0/llms.txt
> - v0.24.1: https://docs.nvidia.com/nemo/guardrails/v0.24.1/llms.txt
> - v0.24.0: https://docs.nvidia.com/nemo/guardrails/v0.24.0/llms.txt
> - v0.23.0: https://docs.nvidia.com/nemo/guardrails/v0.23.0/llms.txt
> - v0.22.0: https://docs.nvidia.com/nemo/guardrails/v0.22.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/guardrails/llms.txt.

# Jailbreak Protection

> Reference for jailbreak protection guardrails that help prevent adversarial attempts from bypassing safety measures.

Jailbreak protection helps prevent adversarial attempts from bypassing safety measures and manipulating the LLM into generating harmful or unwanted content.

## Jailbreak Detection

The NeMo Guardrails library supports jailbreak detection using a set of heuristics. Currently, two heuristics are supported:

1. [Length per Perplexity](#length-per-perplexity)
2. [Prefix and Suffix Perplexity](#prefix-and-suffix-perplexity)

Perplexity is a metric that measures how well a language model predicts text. Lower is better, meaning less randomness or surprise. Typically jailbreak attempts result in higher perplexity.

To activate the jailbreak detection heuristics, you first need include the `jailbreak detection heuristics` flow as an input rail:

```yaml
rails:
  input:
    flows:
      - jailbreak detection heuristics
```

Also, you need to configure the desired thresholds in your `config.yml`:

```yaml
rails:
  config:
    jailbreak_detection:
      server_endpoint: "http://0.0.0.0:1337/heuristics"
      length_per_perplexity_threshold: 89.79
      prefix_suffix_perplexity_threshold: 1845.65
```

> **Note**
>
> If the `server_endpoint` parameter is not set, the checks will run in-process. This is useful for TESTING PURPOSES ONLY and **IS NOT RECOMMENDED FOR PRODUCTION DEPLOYMENTS**.

### Configuration Validation

The jailbreak detection configuration is validated at create-time. Invalid values raise errors
immediately instead of failing silently at runtime. The following validation rules apply:

| Parameter                            | Rule                                    |
| ------------------------------------ | --------------------------------------- |
| `length_per_perplexity_threshold`    | Must be greater than 0                  |
| `prefix_suffix_perplexity_threshold` | Must be greater than 0                  |
| `nim_base_url`                       | Must start with `http://` or `https://` |
| `server_endpoint`                    | Must start with `http://` or `https://` |

### Heuristics

#### Length per Perplexity

The *length per perplexity* heuristic computes the length of the input divided by the perplexity of the input. If the value is above the specified threshold (default `89.79`) then the input is considered a jailbreak attempt.

The default value represents the mean length/perplexity for a set of jailbreaks derived from a combination of datasets including [AdvBench](https://github.com/llm-attacks/llm-attacks), [ToxicChat](https://huggingface.co/datasets/lmsys/toxic-chat/blob/main/README.md), and [JailbreakChat](https://github.com/verazuo/jailbreak_llms), with non-jailbreaks taken from the same datasets and incorporating 1000 examples from [Dolly-15k](https://huggingface.co/datasets/databricks/databricks-dolly-15k).

The statistics for this metric across jailbreak and non jailbreak datasets are as follows:

|      | Jailbreaks | Non-Jailbreaks |
| ---- | ---------- | -------------- |
| mean | 89.79      | 27.11          |
| min  | 0.03       | 0.00           |
| 25%  | 12.90      | 0.46           |
| 50%  | 47.32      | 2.40           |
| 75%  | 116.94     | 18.78          |
| max  | 1380.55    | 3418.62        |

Using the mean value of `89.79` yields 31.19% of jailbreaks being detected with a false positive rate of 7.44% on the dataset.
Increasing this threshold will decrease the number of jailbreaks detected but will yield fewer false positives.

**USAGE NOTES**:

* Manual inspection of false positives uncovered a number of mislabeled examples in the dataset and a substantial number of system-like prompts. If your application is intended for simple question answering or retrieval-aided generation, this should be a generally safe heuristic.
* This heuristic in its current form is intended only for English language evaluation and will yield significantly more false positives on non-English text, including code.

#### Prefix and Suffix Perplexity

The *prefix and suffix perplexity* heuristic takes the input and computes the perplexity for the prefix and suffix. If any of the is above the specified threshold (default `1845.65`), then the input is considered a jailbreak attempt.

This heuristic examines strings of more than 20 "words" (strings separated by whitespace) to detect potential prefix/suffix attacks.

The default threshold value of `1845.65` is the second-lowest perplexity value across 50 different prompts generated using [GCG](https://github.com/llm-attacks/llm-attacks) prefix/suffix attacks.
Using the default value allows for detection of 49/50 GCG-style attacks with a 0.04% false positive rate on the "non-jailbreak" dataset derived above.

**USAGE NOTES**:

* This heuristic in its current form is intended only for English language evaluation and will yield significantly more false positives on non-English text, including code.

### Perplexity Computation

To compute the perplexity of a string, the current implementation uses the `gpt2-large` model.

### Model-based Jailbreak Detections

There is currently one available model-based detection, using a random forest-based detector trained on [`Snowflake/snowflake-arctic-embed-m-long`](https://huggingface.co/Snowflake/snowflake-arctic-embed-m-long) embeddings.

#### Input Length Limit

The `jailbreak detection model` rail accepts up to 2,048 tokens, including special tokens, counted with the Snowflake tokenizer.
It blocks longer inputs before cache lookup, local inference, or a remote detector request.
This limit applies to in-process, `server_endpoint`, and NIM-backed model checks.
The bundled detector server returns HTTP 413 from `/model`, which the rail also treats as a block.

> **Warning**
>
> This is a breaking behavior change for oversized messages. Earlier versions classified only a truncated prefix and could allow the full message to proceed.
> The model rail now rejects the message. Applications must keep each submitted message within the detector's limit, including special tokens.

Input validation uses a bundled, revision-pinned tokenizer and runs offline.
All model checks, including NIM-backed and `server_endpoint` checks, require the `tokenizers` package for this validation.
The standard installation currently includes it through FastEmbed. If it is missing from your environment, install it before enabling the model rail:

```bash
pip install tokenizers
```

NIM-backed checks need no Torch, Transformers, Hugging Face credentials, or model downloads.
Configuration loading raises an error with installation instructions if the model rail is enabled and `tokenizers` is missing.
If the bundled tokenizer cannot be loaded or input coverage cannot be verified at runtime, the rail blocks the request without calling the detector.
Remote requests are sent unchanged only after they pass validation; the model rail also blocks an HTTP 413 returned by the endpoint.

This client-side limit protects calls made through the NVIDIA NeMo Guardrails library.
Direct calls to a hosted NIM endpoint depend on that endpoint's own input handling.

### Detector Availability

Jailbreak detection fails closed when a detector cannot complete its check.
Connection failures, timeouts, non-success responses, and malformed results raise errors instead of returning an allow verdict.
A valid response must contain a boolean `jailbreak` field.
Local model and dependency failures also propagate to engine error handling.

`IORails` stops processing with a failed blocking outcome and an internal-error response.
`LLMRails` uses its action-failure handling to return an internal-error response.
These failures do not mean the detector classified the input as a jailbreak.
Applications using check-only APIs must enforce the returned blocked result before continuing.
Outage failures are not cached as detector verdicts.

HTTP 413 responses from model endpoints and inputs beyond the detector's supported length remain ordinary blocking outcomes, as described above.
There is no fail-open configuration option for this rail.

### Engine Support

| Flow                             | LLMRails | IORails |
| -------------------------------- | :------: | :-----: |
| `jailbreak detection model`      |     ✓    |    ✓    |
| `jailbreak detection heuristics` |     ✓    |    ✗    |

`jailbreak detection heuristics` shares a rail manifest with `jailbreak detection model`, and that manifest declares `torch` and `transformers` as optional dependencies.
`IORails` cannot tell from the manifest alone which of the two flows a configuration is using, and so cannot tell whether those packages are actually required.
Rather than guess, it refuses the flow, and a configuration that uses it routes to `LLMRails` by default.
With `require_iorails=True`, `Guardrails` raises `ValueError` instead of falling back.
This is tracked in [issue #2285](https://github.com/NVIDIA-NeMo/Guardrails/issues/2285).

For the full per-rail matrix, refer to [Rail Engine Support](/nemo/guardrails/v0.25.0/reference/rail-engine-support).

### Setup

The recommended way to use the jailbreak detection heuristics in production is to [deploy the jailbreak detection heuristics server](/nemo/guardrails/v0.25.0/more-deployment-options/using-docker#jailbreak-detection-heuristics) separately. For a hands-on configuration walkthrough, see [Use Jailbreak Detection Heuristics](/nemo/guardrails/v0.25.0/get-started/tutorials/jailbreak-detection-heuristics).

For quick testing, you can use the jailbreak detection heuristics rail locally by first installing `transformers` and `torch`.

```bash
pip install transformers torch
```

### Latency

Latency was tested in-process and via local Docker for both CPU and GPU configurations.
For each configuration, we tested the response time for 10 prompts ranging in length from 5 to 2048 tokens.
Inference times for sequences longer than the model's maximum input length (1024 tokens for GPT-2) necessarily take longer.
Times reported below in are **averages** and are reported in milliseconds.

|            | CPU  | GPU |
| ---------- | ---- | --- |
| Docker     | 2057 | 115 |
| In-Process | 3227 | 157 |