Are you an LLM? You can read better optimized documentation at /docs/agent-guard/policies/cel-context-reference.md for this page in Markdown format
CEL context reference
Every assert expression in a rule is CEL, evaluated against a context the engine builds for that request. Which context you get depends on the policy kind: artifact for ArtifactPolicy, tool for ToolPolicy, guardrail for GuardrailPolicy, and request for both runtime kinds.
This page lists every field the engine exposes, as it is actually populated.
Fields that are not always there
Evaluation is fail-closed, and reading a field that is absent is an evaluation error, so an unguarded rule does not skip the case it did not anticipate: it blocks it, with an engine error in place of your message.
Most fields are always present. Four are conditional and need a has() guard before you touch them:
| Field | Absent when |
|---|---|
artifact.kitfile | The artifact has no Kitfile |
artifact.layers | The artifact has no layers |
tool.session | No session is being tracked for the call |
request.user | The caller supplied no identity |
yaml
assert: |
!has(artifact.kitfile) ||
artifact.kitfile.package.license == "Apache-2.0"Guarding turns a missing Kitfile into your decision with your message. Without the guard, the same artifact fails with no such key: kitfile, which tells the operator nothing.
Three fields are always present but are maps that may be empty, so the risk is the key, not the field. Guard membership before indexing tool.arguments, guardrail.scores, or artifact.annotations:
yaml
assert: |
!("command" in tool.arguments) ||
!tool.arguments.command.contains("rm -rf")Two list fields are always present, empty when there is nothing in them, so exists() over artifact.attestations or guardrail.findings is safe unguarded.
artifact: ArtifactPolicy, admission phase
| Field | Type | Notes |
|---|---|---|
artifact.registry | string | OCI registry hostname. "localhost" for refs resolved from the kitops on-disk store |
artifact.repository | string | Repository path |
artifact.tag | string | Version tag |
artifact.digest | string | Content-addressable digest |
artifact.mediaType | string | Artifact type from the OCI config descriptor, not the manifest media type. This is what match.artifactTypes compares against |
artifact.size | int | Size in bytes |
artifact.annotations | map | OCI annotations. May be empty; guard membership before indexing |
artifact.createdAt | timestamp | Compare with timestamp("..."), not a string |
artifact.pushedBy | string | Pusher identity |
artifact.attestations | list | Always present, empty when there are none. See Attestations for what fills it |
artifact.attestations[].predicateType | string | What hasAttestation() matches on, exactly |
artifact.attestations[].issuer | string | The fingerprint of the trusted cosign key that verified the entry: sha256: and the hex SHA-256 of the key's DER encoding, as agentguard trusted-keys list prints it. It is the same on every machine, whatever file holds the key, and it is what artifact.signedBy() compares against. Not an email or OIDC identity |
artifact.attestations[].predicate | map | Attestation payload. Every field other than the two above lives in here |
artifact.kitfile | map | Conditional. Guard with has(artifact.kitfile). Carries .manifestVersion, .package, .model, and .datasets when present |
artifact.layers | list | Conditional. Entries carry .digest, .mediaType, .size, .annotations |
Attestations
artifact.attestations holds the evidence about an artifact that a trusted key vouches for, in this order:
- One entry for each trusted key (
--pub-key,agentguard trusted-keys add) that verified the artifact's cosign signature, withpredicateType: "cosign"and a predicate carryingsubject,timestampandverified. A key that did not verify gets no entry.predicate.subjectis the reference pinned to the digest that was verified (registry/repo@sha256:...), not the tag; readartifact.tagfor the tag. - The attestations attached to the artifact in its registry, such as SLSA provenance or scan results written with
cosign attest, that one of those same keys signed for this artifact's digest. Each carries the statement'spredicateType, the verifying key's fingerprint asissuer, and the signedpredicateunchanged.
An attestation is a claim about an artifact, not an approval of it, so a registry attestation counts only when its signer also signed the artifact. A trusted key used only to attest, such as a CI key that writes SBOMs, contributes nothing; an attestation copied from another artifact does not match the digest; and a registry attestation of type "cosign" is dropped, so it cannot pose as a signature. Both cosign storage forms are read: the sha256-<digest>.att tag that cosign v2 writes, and cosign v3 bundles among the artifact's referrers.
With no trusted keys, the list is empty and the registry is not read. Jozu Hub attaches its own attestations to the models it imports and to the artifacts it scans (https://kitops.org/attestation/scan/v1), signed with Hub's key. That key is not published, so they do not reach policy. With trusted keys configured, a block or an allow lists them among the registry attestations that did not count.
When registry attestations are read
Admission reads the registry's attestations only for an artifact that a loaded ArtifactPolicy reading them applies to: one whose rules or match expression reach artifact.attestations, or the whole artifact, other than through hasSignature(), signedBy(), attestation("cosign"), hasAttestation("cosign"), or an exists, exists_one or filter whose condition requires predicateType == "cosign". Those read only the first group. A match expression that reads attestations is evaluated with them unknown before they are fetched, so its other conditions still decide whether they are read.
If the registry's attestations cannot all be read (an error, the 30-second limit, more than 64 of them, or one larger than 1 MiB) and an Enforce policy reads them, admission blocks rather than evaluate policy on a partial list, so a rule that denies when an attestation is present cannot pass because that attestation went unread. Anyone who can push to the repository can therefore make such a policy block, by attaching more referrers than the limit; they could equally delete the attestations or replace the artifact. When only Audit policies read them, admission warns and evaluates the ones it read.
A rule that fails to evaluate blocks whatever its action, so an Audit rule should test hasAttestation(t) before it reads attestation(t).predicate.
Writing rules on attestations
To require provenance from a particular signer, test type, issuer and content in one entry:
yaml
assert: |
artifact.attestations.exists(a,
a.predicateType == "https://slsa.dev/provenance/v1" &&
a.issuer == "sha256:9cb72e3348832e977871435269dc833fa96f8f7b34f445be3de2d29890c75fbc" &&
a.predicate.buildDefinition.buildType == "https://example.com/build/v1")artifact.signedBy(k) && artifact.hasAttestation(t) is weaker: two different entries can satisfy it.
Require the attestation in the same rule that reads its content, as above, so a missing attestation denies. The two ways of writing a scan rule show why this matters. A rule that requires a clean scan and a rule that forbids a failing one agree when a trusted scan is present, and differ when there is none: the first denies, the second allows. Write the first when an artifact without a trusted scan should not run.
Someone who can push to the artifact's repository but holds no trusted key cannot add an attestation that counts. One signed with their own key has no trusted issuer, and one copied from another artifact names the wrong digest. They can do two things:
- Delete attestations. A rule that requires a trusted attestation then denies, and a rule that forbids a failing one then allows. This is why the first form is the one to write.
- Push back an older statement that a trusted key signed for the same digest. Policy cannot tell it from a newer one, so if a later scan of the artifact failed, the earlier clean scan can be restored and pass.
Limit who can push to the repositories you admit from. When statements a key signed must stop counting, rotate the key: sign the artifacts you still trust, and their attestations, with a new key, and write rules on the new key's fingerprint, which nothing the old key signed matches.
The digest itself is fixed: agentguard run resolves the agent definition, each base and each module to a digest at its registry once, then admits and pulls that digest, so the attestations a rule read describe what runs.
Because a rule that requires an attestation denies every artifact without one, start it as Audit to see which artifacts in your estate carry the attestation before it blocks.
tool: ToolPolicy, runtime phase
| Field | Type | Notes |
|---|---|---|
tool.name | string | Tool name, e.g. Bash, Read, WebFetch |
tool.server | string | MCP server that exposes the tool |
tool.serverVersion | string | MCP server version |
tool.title | string | Human-readable tool title |
tool.description | string | Tool description |
tool.arguments | map | Tool-specific. Bash sends command, Read sends file_path, Grep sends pattern. Guard membership before reading any of them |
tool.session | map | Conditional. Carries .toolCalls, .thisToolCalls (ints) and .lastCallTime (timestamp) |
Tool and argument names come from the agent, not from Agent Guard, so they differ across agents. The shell tool is Bash in Claude Code and run_command in Antigravity CLI, and the file-reading tool is Read in Claude Code and view_file in Antigravity CLI. Antigravity CLI names the arguments differently (CommandLine, AbsolutePath). Agent Guard passes both key sets, the agent's own and command and file_path alongside them, so a rule written against command or file_path covers both agents once both tool names are in its match list.
guardrail: GuardrailPolicy, runtime phase
| Field | Type | Notes |
|---|---|---|
guardrail.name | string | Scanner name |
guardrail.version | string | Scanner version |
guardrail.direction | string | input, output or both |
guardrail.content.turn | text | The current turn's text. Empty when the turn carries no text of its own, such as a turn that is only an attachment |
guardrail.content.raw | text | The request body as sent, with binary payloads such as base64 images left out |
guardrail.content.canonical | text | Every string value, object key and number in the body, decoded, one per line in document order. Carries the conversation history, tool calls and tool results. Equal to raw for a body that is not JSON |
guardrail.content.files | files | Text extracted from attachments, one entry per file |
guardrail.scores | map(string, double) | Only the keys the attached scanner produces. Guard membership before indexing |
guardrail.findings | list | Detections reported by scanners. Always present, empty when there are none |
guardrail.findings[].category | string | The scanner's category, or uninspected (see below) |
guardrail.findings[].severity | string | Scanner-assigned severity |
guardrail.findings[].message | string | The located text when the finding has a span, otherwise the scanner's description |
guardrail.findings[].span | map | Conditional. Carries .start and .end byte offsets, and .content and .index naming the input and file they fall in |
Content inputs
The four guardrail.content inputs are the request text, and a rule can test them but cannot read them. Each supports three calls and nothing else:
| Call | True when |
|---|---|
matches(re) | The RE2 pattern matches somewhere in the input. On files, in any file |
contains(s) | The input contains the substring. On files, any file does |
isEmpty() | The input has no text. On files, no attachment yielded text, which includes one the extractor could not read |
Converting an input to a string, concatenating it, measuring it with size(), or comparing it with == fails when the policy loads, so no rule can compare content in a way that never fires. The restriction also lets Redact mask only what matched: the engine records which input and which pattern made a rule fire, and masks that text. When a rule fires on something it cannot locate, such as isEmpty(), a score, or a pattern that matches the empty string, Redact masks the whole current turn. A match on an object key or a number in canonical has no text to edit, so it denies the request. Because Redact masks exactly the text a pattern matched, the pattern has to cover the whole secret, not a marker next to it. A pattern that matches only a private key's -----BEGIN ... PRIVATE KEY----- line masks that line and sends the key itself in clear; match through the -----END ... PRIVATE KEY----- line instead.
Which input to test decides what a rule can see. "Anywhere in the request" is canonical or files:
yaml
assert: |
!(guardrail.content.canonical.matches("BEGIN (RSA |EC |OPENSSH |PGP )?PRIVATE KEY") ||
guardrail.content.files.matches("BEGIN (RSA |EC |OPENSSH |PGP )?PRIVATE KEY"))turn alone misses a secret that arrives in an attachment, a tool result, or an earlier turn. canonical sees all of those, and the cost is that it carries history: an Enforce match on it repeats on every later turn of the conversation, and the user recovers only by starting a new one. Use Redact for a rule on canonical when that trade is wrong for your users, or test turn and files when only new content should count.
canonical decodes each JSON string once. Text that is itself JSON inside a string, such as a tool call's arguments or a tool result, stays escaped, so a line there starts after the two characters \n rather than a newline. A pattern that anchors on a line boundary should accept the escaped form too: inside a CEL string literal that is \\\\[nrt], which the regex engine reads as a backslash followed by n, r or t.
body, full_body, json and file are not finding categories. A rule that compares a finding's category with one of them using ==, != or in fails to load, and the failure is not confined to its own policy: the engine refuses the whole policy set, the gateway does not start, and agentguard run stops before the agent starts, naming the rule and the source it came from. Test guardrail.content instead. Any other use of those names loads and never matches.
guardrail.findings holds detections, not request text. A rule such as guardrail.findings.exists(f, f.message.matches(R)) loads, but it sees only what a scanner reported, so with no scanner attached it never fires. Write content rules against guardrail.content.
Attachment text comes from Word, Excel and PowerPoint documents, plain-text formats (.txt, .md, .csv, .tsv, .json, .xml, .yaml), PDFs with a text layer, and images through OCR. A file the extractor cannot open contributes no text to files: a scanned PDF with no text layer, a password-protected PDF, an unrecognized archive, or an image carrying no recognizable text. No rule can match what was not read, so this is the one place where guardrail evaluation fails open, and attachment scanning is a net rather than a boundary. A turn with an attachment that could not be inspected carries one finding with category uninspected, whether the attachment was forwarded or stripped, and a policy that must refuse what it cannot read can say so:
yaml
assert: |
!guardrail.findings.exists(f, f.category == "uninspected")The engine extracts attachments only when a loaded rule names guardrail.content.files or a scanner is attached, so this rule needs one of those beside it.
An unguarded score lookup is the most damaging mistake available in a guardrail policy. guardrail.scores["toxicity"] < 0.7 with no scanner wired means the key is absent, CEL raises, and fail-closed evaluation blocks every model request in the deployment. Written with a guard, the rule stays dormant until a scanner supplies the score and then takes effect on its own:
yaml
assert: |
!("toxicity" in guardrail.scores) ||
guardrail.scores["toxicity"] < 0.7request: both runtime kinds
| Field | Type | Notes |
|---|---|---|
request.action | string | Requested action |
request.sessionId | string | Session identifier |
request.conversationId | string | Conversation identifier |
request.timestamp | timestamp | Request time |
request.clientIp | string | Originating IP |
request.userAgent | string | Client user agent |
request.elicitation | map | Always present. Defaults to responded: false, action: "", content: {} when no elicitation is in flight |
request.user | map | Conditional. Carries .id, .type, .roles, .groups, .attributes |
Helper functions
| Call | Returns | Notes |
|---|---|---|
artifact.hasSignature() | bool | True when attestations is non-empty. Under Agent Guard that means a trusted key verified the signature, because every entry's signer has signed the artifact |
artifact.signedBy(id) | bool | True when some attestation's issuer equals id exactly. Compare against a key fingerprint, per issuer above. Registry attestations do not change the answer: their issuers have all signed the artifact |
artifact.hasAttestation(type) | bool | True when some attestation's predicateType equals type exactly |
artifact.attestation(type) | map or null | First matching attestation, null when none matches. Reading a field off null fails, so pair it with hasAttestation() |
<string>.isInternalIP() | bool | Called on a URL or bare IP string, not on a context object. Parses the URL, then tests the host against the private ranges |
A policy that requires a particular signer names its fingerprint:
yaml
assert: |
artifact.signedBy("sha256:9cb72e3348832e977871435269dc833fa96f8f7b34f445be3de2d29890c75fbc")A rule that names a key file path never matches, so it denies every artifact. Take the fingerprint from agentguard trusted-keys list.
CEL dialect notes
Strings expose .contains(substring), .startsWith(prefix), .endsWith(suffix), .matches(regex), .size(), and concatenation with +.
.contains() is substring matching, not regex: .contains("curl") matches concurly as well as curl https://example.com. Use .matches() when you need a boundary.
Regular expressions are RE2. There are no backreferences and no lookahead, so some patterns cannot be written as a single expression and have to be split across rules or restructured. Character classes survive YAML quoting better than backslash escapes: [.]env and \.env mean the same thing to RE2, but [.] cannot be mangled on its way through the parser.
A literal regex that does not compile fails the policy at load time rather than at evaluation time, which means a bad pattern is caught by gerty validate instead of blocking an agent later.
