Background
Controls in openssf-baseline.toml (and other implementations) use CEL expressions in expr fields. The available context variables depend on the handler:
exec: output.stdout, output.stderr, output.exit_code, output.jsonapi: response.status_code, response.body, response.headerspattern: files, matches- All:
project.* (from .project/project.yaml)
Custom CEL functions: file_exists(path), json_path(obj, path).
Today these are documented in the project CLAUDE.md, which is aimed at agents, not at control authors writing TOML.
Problem
A new control author (internal or plugin) has no discoverable reference for what they can write in expr. They either grep other controls for examples or guess. Both paths risk silently-wrong CEL (e.g., referencing output.json when the command did not return JSON).
Proposal
Add a docs page under docs/ that lists:
- CEL context variables per handler type.
- Custom functions with signatures and examples.
- Common patterns (exit-code + expr, JSON path traversal, negated grep).
Keep it short and cross-link from the framework-design doc.
Related
docs/architecture/framework-design.md- Handler implementations in
packages/darnit/src/darnit/sieve/builtin_handlers.py
Background
Controls in
openssf-baseline.toml(and other implementations) use CEL expressions inexprfields. The available context variables depend on the handler:exec:output.stdout,output.stderr,output.exit_code,output.jsonapi:response.status_code,response.body,response.headerspattern:files,matchesproject.*(from.project/project.yaml)Custom CEL functions:
file_exists(path),json_path(obj, path).Today these are documented in the project
CLAUDE.md, which is aimed at agents, not at control authors writing TOML.Problem
A new control author (internal or plugin) has no discoverable reference for what they can write in
expr. They either grep other controls for examples or guess. Both paths risk silently-wrong CEL (e.g., referencingoutput.jsonwhen the command did not return JSON).Proposal
Add a docs page under
docs/that lists:Keep it short and cross-link from the framework-design doc.
Related
docs/architecture/framework-design.mdpackages/darnit/src/darnit/sieve/builtin_handlers.py