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

# Common Expression Language (CEL)

> Reference for the per-tool rail that blocks tool calls or tool results matching Common Expression Language (CEL) expressions you write per tool.

The CEL rail checks a tool call's arguments, or a tool result's content, against [Common Expression Language (CEL)](https://cel.dev) expressions that you write per tool. CEL is a small, side-effect-free expression language used for policy rules in systems such as Kubernetes admission policies and Envoy. Each expression evaluates to `true` when the tool is being used in a way you want to block.

Unlike [Regex Detection](/nemo/guardrails/v0.25.0/configure-guardrails/guardrail-catalog/third-party/regex), which matches text patterns, CEL expressions address the structured fields of a tool call directly, so one rule can combine several arguments. Unlike [Tool Safety Check](/nemo/guardrails/v0.25.0/configure-guardrails/guardrail-catalog/tool-safety-check), the check is deterministic and calls no model. It is scoped per tool through the same `rails.tool_call.per_tool` and `rails.tool_result.per_tool` dispatch mechanism as both.

## Installation

The CEL rail requires the optional `cel` extra, which installs the [`common-expression-language`](https://pypi.org/project/common-expression-language/) package and is available on Python 3.11 and later:

```bash
pip install "nemoguardrails[cel]"
```

If the extra is not installed, a configuration that uses the CEL rail fails to load with an error naming the extra.

## Configure the Rail

To use the CEL rail, you should:

1. Write the expressions for each tool in the `rails.config.cel` section of the `config.yml` file, under `tool_call` to check tool calls and `tool_result` to check tool results:

   ```yaml
   rails:
     config:
       cel:
         tool_call:
           run_shell:
             expressions:
               - 'args.command.matches("(?i)\\brm\\s+-[a-z]*(r[a-z]*f|f[a-z]*r)")'
           write_file:
             expressions:
               - 'args.path.startsWith("/etc/") || args.path.startsWith("/root/")'
               - 'has(args.mode) && args.mode == "append" && args.path.endsWith(".bashrc")'
         tool_result:
           run_shell:
             expressions:
               - 'type(result) == string && result.contains("BEGIN RSA PRIVATE KEY")'
   ```

2. Scope the check to the tool in the `tool_call` and `tool_result` rails sections of the `config.yml` file:

   ```yaml
   rails:
     tool_call:
       per_tool:
         run_shell:
           - "cel check tool call"
         write_file:
           - "cel check tool call"
     tool_result:
       per_tool:
         run_shell:
           - "cel check tool result"
   ```

   The `cel check tool call` flow evaluates the tool's `tool_call` expressions against each call to the tool, and the `cel check tool result` flow evaluates its `tool_result` expressions against each result the tool returns. A tool without a CEL flow under `per_tool` is not checked by the rail, but a tool whose CEL flow has no expressions configured for its direction fails closed.

3. Declare the tool in the main model's `parameters.tools`, or per request: in `options.llm_params.tools` with the Python API, or in the `tools` field of a chat completions request to the server, which the server currently accepts only for non-streaming requests on a configuration with `passthrough: true`. `cel check tool call` blocks a call to an undeclared tool before any expression runs. Refer to [Tool Calling](/nemo/guardrails/v0.25.0/configure-guardrails/guardrail-catalog/tool-calling) for the full declaration reference.

The `cel check tool call` and `cel check tool result` rails execute the [`evaluate_tool_call_cel`](https://github.com/NVIDIA-NeMo/Guardrails/blob/develop/nemoguardrails/library/cel/actions.py) and [`evaluate_tool_result_cel`](https://github.com/NVIDIA-NeMo/Guardrails/blob/develop/nemoguardrails/library/cel/actions.py) actions respectively.

## Expression Variables

Each expression can read the following variables:

| Flow                    | Variable | Value                                                                                                     |
| ----------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `cel check tool call`   | `args`   | The tool call's arguments, as a map                                                                       |
|                         | `tool`   | The tool's name                                                                                           |
| `cel check tool result` | `result` | The tool result's content, exactly as the tool returned it: a string, a list of content blocks, or `null` |
|                         | `args`   | The arguments of the tool call that the result answers                                                    |
|                         | `tool`   | The tool's name                                                                                           |

Nested arguments are available at any depth, for example `args.options.recursive` or `args.files.exists(f, f.path.startsWith("/etc"))`.

A tool result that contains JSON text is still a string, so check it with string functions such as `contains()` and `matches()`.

## How Expressions Are Evaluated

The rail evaluates every expression configured for the tool:

* If any expression evaluates to `true`, the rail blocks the tool call or result. The block lists the expressions that matched in its `matched_expressions` metadata. The metadata never includes the checked arguments or content.
* If no expression evaluates to `true`, the rail allows the tool call or result.
* If any expression fails to evaluate, for example because it reads an argument the call did not include, or it returns a value that is not a boolean, the rail fails closed, even if another expression matched. The tool call or result is blocked and reported as a rail failure rather than a policy decision, and the logged error lists each expression that failed with its error type.
* If the tool has no expressions configured for the direction its flow runs in, the rail also fails closed, since there is nothing to validate the tool call or result against.

## Write Expressions

Expressions use [CEL syntax](https://github.com/google/cel-spec/blob/master/doc/langdef.md), including comparisons, `&&` and `||`, the `in` operator, the `exists()` and `all()` macros, and string functions such as `contains()`, `startsWith()`, `endsWith()`, and `matches()`, which uses RE2 regular expression syntax. The rail also provides the cel-go extension functions, such as `lowerAscii()`, `split()`, and `lists.range()`.

When you write expressions, keep the following in mind:

* Guard optional arguments with `has()`, for example `has(args.mode) && args.mode == "append"`. Without the guard, a call that omits the argument fails to evaluate.
* If a tool can return either a string or a list of content blocks, check the type first, for example `type(result) == string && result.contains("password")`.
* Each expression must evaluate to a boolean. An expression such as `args.command` that returns a string fails to evaluate.

The rail checks each expression's syntax when the configuration loads, so a syntax error fails the load. Everything else is checked when an expression is evaluated: the CEL library the rail uses resolves variable and function names only at evaluation, and `args` and `result` hold the values of each tool call or result, so whether a field exists or has the expected type is known only then. A mistake found at evaluation makes the rail fail closed, so test your expressions against representative tool calls and results before deploying them.

## Complete Example

The following configuration blocks recursive forced deletes in `run_shell`, writes to `/etc` or `/root` and appends to `.bashrc` through `write_file`, and any `run_shell` result that contains a private key:

> **Warning**
>
> The expressions on this page illustrate how the rail works; they are not complete security policies. Write and test expressions for the actual threats your tools face.

```yaml
models:
  - type: main
    engine: nim
    model: meta/llama-3.3-70b-instruct

rails:
  config:
    cel:
      tool_call:
        run_shell:
          expressions:
            - 'args.command.matches("(?i)\\brm\\s+-[a-z]*(r[a-z]*f|f[a-z]*r)")'
        write_file:
          expressions:
            - 'args.path.startsWith("/etc/") || args.path.startsWith("/root/")'
            - 'has(args.mode) && args.mode == "append" && args.path.endsWith(".bashrc")'
      tool_result:
        run_shell:
          expressions:
            - 'type(result) == string && result.contains("BEGIN RSA PRIVATE KEY")'
  tool_call:
    per_tool:
      run_shell:
        - "cel check tool call"
      write_file:
        - "cel check tool call"
  tool_result:
    per_tool:
      run_shell:
        - "cel check tool result"
```

> **Note**
>
> This configuration doesn't declare `run_shell` or `write_file`. Declare them in the main model's `parameters.tools`, or per request: in `options.llm_params.tools` with the Python API, or in the `tools` field of a chat completions request to the server, which the server currently accepts only for non-streaming requests on a configuration with `passthrough: true`. Otherwise `cel check tool call` blocks every call to them before any expression runs. Refer to [Tool Calling](/nemo/guardrails/v0.25.0/configure-guardrails/guardrail-catalog/tool-calling) for the declaration format.

## Schema Validation

`cel check tool call` runs behind `@tool_call_validation`: a call to a tool the model has not declared, or whose arguments violate the tool's declared JSON schema, is blocked before any expression is evaluated. `cel check tool result` has no such gate, matching regex detection's asymmetry between the two directions.

## Engine Support

| Flow                    | LLMRails | IORails |
| ----------------------- | :------: | :-----: |
| `cel check tool call`   |     ✗    |    ✓    |
| `cel check tool result` |     ✗    |    ✓    |

Per-tool checks are an `IORails`-only capability by design. For the full per-rail matrix, refer to [Rail Engine Support](/nemo/guardrails/v0.25.0/reference/rail-engine-support).