CEL policies

Match authenticated, structured tool calls with bounded CEL expressions and turn matches into DefenseClaw findings.

How the CEL engine runs, how to write CEL rules, and the tool-call state they can read.

CEL engine

Understand DefenseClaw's typed ActionFacts projection, CEL admission rules, bounded evaluation, semantic ownership, and fallback behavior.

CEL authoring

The CEL rule-file contract, ActionFacts fields, enum families and expression patterns for DefenseClaw rule packs.

Tool-call state

How authenticated connector hooks prove outcomes, commit ordered tool-call state, and preserve conservative enforcement guarantees.

Where CEL fits

List view for small screens. Use the expand button to open the drawing.

Tool call arrivesfrom a connector hook or inspect call
- sendsGateway parses the arguments
Gateway parses the argumentscommands, paths, network, data flow
- fully parsedCEL expression
- not fully parsedRule's regex pattern
Rule's regex patternmatches the raw text
- matchesFinding
CEL expressionmatches the parsed facts
- trueFinding
Findingtitle and severity from the YAML
- checkedFully proven for this rule?
Fully proven for this rule?and the connector can block
- yesSeverity picks the action
- noDetection only
Detection onlyrecorded, action unchanged
Severity picks the actionallow · alert · confirm · block

How a CEL rule turns a tool call into an action. Static tool block and allow lists are checked before this. If a CEL expression errors or runs out of budget, that rule falls back to its regex pattern.

The connector's authenticated hook route, or a trusted inspect call, decides that a request is a tool call. A payload cannot mark itself as structured. DefenseClaw parses the arguments into private ActionFacts and exposes them to CEL as one typed variable, f. Each rule takes exactly one route: its CEL expression when the arguments are fully parsed, or its own regex pattern when they are not. Both routes produce the finding defined in the YAML. A finding changes the action only when DefenseClaw's own code holds complete proof for that same rule ID and the connector can block. A regex match on its own is recorded as detection-only.

Start with a complete rule

Shell examples

The shell examples require Bash. On native Windows, use Git Bash or WSL; PowerShell uses different continuation and environment-variable syntax.

This section adds one rule that flags any command that reads /srv/payments/secrets. The rule goes in a copy of the default pack, so the bundled rules stay as they are.

Before you start: DefenseClaw is initialized (defenseclaw init). The paths below are ~/.defenseclaw/...; the sample output shows /home/alice.

Copy the closest bundled pack.

cp -r ~/.defenseclaw/policies/guardrail/default \
      ~/.defenseclaw/policies/guardrail/my-org

Add a rules file with a category no other file uses.

~/.defenseclaw/policies/guardrail/my-org/rules/my-org.yaml

version: 1
category: my-org
rules:
  - id: ORG-PAYMENTS-SECRETS
    tool_call_only: true
    expression: >-
      f.commands.exists(c,
      defenseclaw.guardrail.semantic.v1.OperationKind.OPERATION_KIND_READ in c.operations &&
      f.paths.exists(p, p.command_id == c.id &&
      p.access == defenseclaw.guardrail.semantic.v1.PathAccess.PATH_ACCESS_READ &&
      (p.resolved == '/srv/payments/secrets' ||
      p.resolved.startsWith('/srv/payments/secrets/'))))
    pattern: '(?i)(?:^|\s)/srv/payments/secrets(?:/|\s|$)'
    title: "Payments secret directory read"
    severity: CRITICAL
    confidence: 0.95
    tags: [credential, payments, file-sensitive]

expression matches the parsed command and path facts; it joins the path to its command by id. pattern is the required regex fallback for calls the gateway cannot fully parse. A fallback match is recorded but does not block. The rule supplies the title and severity; the block and alert levels pick the action. Field names are in the CEL authoring reference.

Validate and activate

Validate the whole pack. This runs offline and does not touch the gateway.

defenseclaw guardrail validate-pack ~/.defenseclaw/policies/guardrail/my-org

Rule pack valid: "/home/alice/.defenseclaw/policies/guardrail/my-org"
  rules: 240/244 enabled across 8 files
  components: judges=4 judge_categories=23 local_patterns=11 suppressions=9 sensitive_tools=6
  digest: b8f9965c2ff04e19c30558758b5ae3e56423480a85d7479cd0d90b26ed13e9e0
  files digest: 4b04e4ffa078aff3ea14b708257ecb81a62c4e01611ba0b0b3063411888fa71b (the guardrail.custom_packs pin)

The default pack has 246 rules in 7 files; yours has 247 in 8. Exit codes: 0 valid, 1 invalid, 2 validator unavailable.

Pin the pack and switch to it.

defenseclaw guardrail use-pack ~/.defenseclaw/policies/guardrail/my-org

  OK All connectors now use the 'my-org' rule pack. Saved (config generation 3). The gateway isn't running; it loads this when it starts.

Add --connector codex to switch one agent. A running gateway loads the pack on its next reload.

Check it worked

defenseclaw guardrail list-packs
defenseclaw config get guardrail.custom_packs

  * custom packs:
      - my-org: /home/alice/.defenseclaw/policies/guardrail/my-org (used by global, codex)

my-org:
  digest: sha256:4b04e4ffa078aff3ea14b708257ecb81a62c4e01611ba0b0b3063411888fa71b
  path: /home/alice/.defenseclaw/policies/guardrail/my-org

Compilation does not prove a connector supplies the facts your expression reads. In observe mode, run a real command that reads the directory and a near miss, then inspect the connector's native decision and its recent alerts:

defenseclaw alerts --limit 25 --connector claudecode
defenseclaw alerts --connector claudecode --show 1

Use the connector you tested in both commands and the alert number from the list, so --show numbers the list you just read. Secret findings hide rule IDs and titles in both alert views: this rule can appear as redacted.secret.id-… with the title Secret finding. Searching alerts for ORG-PAYMENTS-SECRETS will not find that redacted entry. Correlate the alert's connector, time and session with your test turn. For direct verification of the original ID, use the connector's native action verdict on a harmless matching test; observe-mode alert views cannot recover it. The pack path and files digest above establish which reviewed rules are configured; they do not prove a hook exercised this rule. No CLI injects synthetic facts.

With the default pack's levels, this CRITICAL rule can block in action mode when the facts are complete. A HIGH rule would alert only.

Undo

defenseclaw guardrail use-pack default

This also removes the pin for my-org.

Choose the next page

Next: validate a pack in CI, regex patterns for the fallback, pinned pack edits.