Skip to navigation

Common Expression Language (CEL)

View as MarkdownOpen in Claude

The CEL rail checks a tool call’s arguments, or a tool result’s content, against Common Expression Language (CEL) 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, 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, 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 package and is available on Python 3.11 and later:

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:

    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:

    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 for the full declaration reference.

The cel check tool call and cel check tool result rails execute the evaluate_tool_call_cel and evaluate_tool_result_cel actions respectively.

Expression Variables

Each expression can read the following variables:

FlowVariableValue
cel check tool callargsThe tool call’s arguments, as a map
toolThe tool’s name
cel check tool resultresultThe tool result’s content, exactly as the tool returned it: a string, a list of content blocks, or null
argsThe arguments of the tool call that the result answers
toolThe 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, 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:

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.

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"

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

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