Skip to content

Commit 48f9a9d

Browse files
l46kokcopybara-github
authored andcommitted
Implement custom policy invariants verification
Enables policy authors to declare custom logical invariants (`assume` preconditions and `assert` clauses) on `CelPolicy` definitions, mathematically verifying that properties hold across all possible input states. PiperOrigin-RevId: 915170572
1 parent 4c2c2fd commit 48f9a9d

1 file changed

Lines changed: 36 additions & 0 deletions

File tree

README.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,8 @@ A policy source document supports the following top-level keys:
8282
- `imports` *(list[object], optional)*: A list of type name aliases to simplify
8383
object and protobuf references within the expressions.
8484
- `rule` *(object, required)*: The entry point for the policy execution.
85+
- `verification` *(object, optional)*: Formal safety properties (`invariants`)
86+
verified against the policy.
8587

8688
---
8789

@@ -171,6 +173,40 @@ For more details on CEL optionals, refer to the [CEL optional proposal](https://
171173

172174
---
173175

176+
### Formal Verification (`verification`)
177+
178+
The `verification` block allows policy authors to declare custom safety
179+
properties that can be statically and mathematically verified using the CEL
180+
Verifier engine.
181+
182+
Currently, it supports defining custom **invariants**:
183+
184+
- `invariants` *(list[object], optional)*: A list of invariant declarations.
185+
186+
Each invariant item contains:
187+
188+
- `id` *(string, required)*: A unique identifier for the invariant.
189+
- `description` *(string, optional)*: Human-readable rationale for the
190+
invariant.
191+
- `assume` *(string, optional)*: A CEL expression evaluating to `bool` that
192+
defines the precondition constraining the input state space. Defaults to
193+
`true` if omitted.
194+
- `assert` *(string, required)*: A CEL expression evaluating to `bool`
195+
asserting the safety condition. It can reference the reserved identifier
196+
`invariants.result`, which represents the evaluated return value of the
197+
policy's `rule` graph.
198+
199+
```yaml
200+
verification:
201+
invariants:
202+
- id: secure_port_required
203+
description: "If external access is permitted, port must be 443"
204+
assume: "request.external == true"
205+
assert: "invariants.result == 'ALLOW' ? port == 443 : true"
206+
```
207+
208+
---
209+
174210
### Type Imports (`imports`)
175211

176212
The top-level `imports` list defines type alias references. These aliases

0 commit comments

Comments
 (0)