Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 28 additions & 15 deletions verifier/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ properties about your expressions.
runtime partial evaluation.

```java
CelVerifier verifier = CelVerifierFactory.newVerifier()
CelVerifier verifier = CelVerifierFactory.newVerifier(cel)
.addUnknownIdentifier("request.headers") // Exclude unknown fields from failure paths
.build();
```
Expand Down Expand Up @@ -85,10 +85,10 @@ The following example demonstrates how to verify if two CEL expressions
are logically equivalent.

```java
import dev.cel.bundle.Cel;
import dev.cel.bundle.CelFactory;
import dev.cel.common.CelAbstractSyntaxTree;
import dev.cel.common.types.SimpleType;
import dev.cel.compiler.CelCompiler;
import dev.cel.compiler.CelCompilerFactory;
import dev.cel.verifier.CelVerificationException;
import dev.cel.verifier.CelVerificationResult;
import dev.cel.verifier.CelVerificationResult.VerificationStatus;
Expand All @@ -98,16 +98,16 @@ import java.time.Duration;

public class VerifierExample {
public static void main(String[] args) throws Exception {
CelCompiler compiler = CelCompilerFactory.standardCelCompilerBuilder()
Cel cel = CelFactory.plannerCelBuilder()
.addVar("x", SimpleType.INT)
.build();

// Compile two logically equivalent expressions
CelAbstractSyntaxTree astA = compiler.compile("x > 10").getAst();
CelAbstractSyntaxTree astB = compiler.compile("10 < x").getAst();
CelAbstractSyntaxTree astA = cel.compile("x > 10").getAst();
CelAbstractSyntaxTree astB = cel.compile("10 < x").getAst();

// Create and configure the verifier
CelVerifier verifier = CelVerifierFactory.newVerifier()
CelVerifier verifier = CelVerifierFactory.newVerifier(cel)
.setTimeout(Duration.ofSeconds(2))
.build();

Expand Down Expand Up @@ -142,7 +142,8 @@ public class VerifierExample {

### 2. Policy Equivalence Verification

You can also verify the equivalence of two structured CEL Policies.
You can also verify the equivalence of two structured CEL Policies. Build the
policy compiler and the AST verifier from the same `Cel` environment.

```java
import dev.cel.bundle.Cel;
Expand Down Expand Up @@ -176,7 +177,7 @@ public class PolicyVerifierExample {
CelPolicyCompilerFactory.newPolicyCompiler(CEL).build();

// Verifiers are immutable and thread-safe, making them safe to store as static constants
private static final CelVerifier AST_VERIFIER = CelVerifierFactory.newVerifier().build();
private static final CelVerifier AST_VERIFIER = CelVerifierFactory.newVerifier(CEL).build();

private static final CelPolicyVerifier POLICY_VERIFIER =
CelPolicyVerifierFactory.newVerifier(POLICY_COMPILER, AST_VERIFIER).build();
Expand Down Expand Up @@ -245,27 +246,27 @@ provides concrete satisfying model assignments (witness/test case generation),
and `result.witness()` exposes them as CEL runtime values.

```java
import dev.cel.bundle.Cel;
import dev.cel.bundle.CelFactory;
import dev.cel.common.CelAbstractSyntaxTree;
import dev.cel.common.types.SimpleType;
import dev.cel.compiler.CelCompiler;
import dev.cel.compiler.CelCompilerFactory;
import dev.cel.verifier.CelVerificationResult;
import dev.cel.verifier.CelVerificationResult.VerificationStatus;
import dev.cel.verifier.CelVerifier;
import dev.cel.verifier.CelVerifierFactory;

public class SatisfiabilityExample {
public static void main(String[] args) throws Exception {
CelCompiler compiler = CelCompilerFactory.standardCelCompilerBuilder()
Cel cel = CelFactory.plannerCelBuilder()
.addVar("role", SimpleType.STRING)
.addVar("port", SimpleType.INT)
.build();

// Check if an authorization condition can ever be met
CelAbstractSyntaxTree ast =
compiler.compile("role == 'editor' && port > 1024 && port < 65535").getAst();
cel.compile("role == 'editor' && port > 1024 && port < 65535").getAst();

CelVerifier verifier = CelVerifierFactory.newVerifier().build();
CelVerifier verifier = CelVerifierFactory.newVerifier(cel).build();
CelVerificationResult result = verifier.isSatisfiable(ast);

switch (result.status()) {
Expand Down Expand Up @@ -322,7 +323,7 @@ public class InvariantsExample {
private static final CelPolicyCompiler POLICY_COMPILER =
CelPolicyCompilerFactory.newPolicyCompiler(CEL).build();

private static final CelVerifier AST_VERIFIER = CelVerifierFactory.newVerifier().build();
private static final CelVerifier AST_VERIFIER = CelVerifierFactory.newVerifier(CEL).build();

private static final CelPolicyVerifier POLICY_VERIFIER =
CelPolicyVerifierFactory.newVerifier(POLICY_COMPILER, AST_VERIFIER).build();
Expand Down Expand Up @@ -408,6 +409,18 @@ by the Z3 solver during its search phase.
If the solver times out, the verifier will throw a `CelVerificationException`
which should be explicitly caught and handled by the caller.

### Validating Counterexamples with the CEL Runtime

`enableCegar(true)` checks the inputs the solver finds with the CEL runtime of
the verifier's environment: a confirmed `INCONCLUSIVE` counterexample (or
satisfying input) becomes `VIOLATED` (or `VERIFIED`), and any refuted one becomes
`INCONCLUSIVE`. Only exact inputs are checked, when no unknown identifiers are
registered; when the runtime can't evaluate them (e.g. a function has no
binding), the message says why. The runtime must follow the CEL spec (e.g.
`CelOptions.DEFAULT`, which has no iteration limit), and a function with
bindings must have one for each overload, which is synchronous, deterministic
and doesn't throw.

### Comprehensions and Bounded Model Checking

Because CEL lists/maps can be dynamically sized, the verifier cannot
Expand Down
11 changes: 7 additions & 4 deletions verifier/src/main/java/dev/cel/verifier/BUILD.bazel
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,6 @@ java_library(
deps = [
"//:auto_value",
"//common:cel_ast",
"//common/types:type_providers",
"@maven//:com_google_errorprone_error_prone_annotations",
"@maven//:com_google_guava_guava",
],
Expand Down Expand Up @@ -170,6 +169,7 @@ java_library(
"CelZ3StructTranslator.java",
"CelZ3TranslationContext.java",
"CelZ3TypeConstraintGenerator.java",
"RuntimeOracle.java",
"TranslatedValue.java",
],
compatible_with = [],
Expand All @@ -184,12 +184,12 @@ java_library(
"//bundle:cel",
"//common:cel_ast",
"//common:compiler_common",
"//common:error_codes",
"//common:operator",
"//common/ast",
"//common/ast:cel_block",
"//common/internal:cel_descriptor_pools",
"//common/exceptions:runtime_exception",
"//common/internal:proto_time_utils",
"//common/internal:well_known_proto",
"//common/types",
"//common/types:cel_types",
"//common/types:type_providers",
Expand All @@ -198,10 +198,13 @@ java_library(
"//optimizer",
"//optimizer:optimization_exception",
"//optimizer:optimizer_builder",
"//runtime",
"//runtime:function_resolver",
"//runtime:resolved_overload",
"//runtime:unknown_attributes",
"//verifier/axioms",
"@maven//:com_google_errorprone_error_prone_annotations",
"@maven//:com_google_guava_guava",
"@maven//:com_google_protobuf_protobuf_java",
"@maven//:org_jspecify_jspecify",
"@maven//:tools_aqua_z3_turnkey",
],
Expand Down
86 changes: 48 additions & 38 deletions verifier/src/main/java/dev/cel/verifier/CelAstToZ3Translator.java
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@

package dev.cel.verifier;

import static com.google.common.base.Preconditions.checkArgument;

import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableSet;
import com.google.common.collect.ImmutableSortedSet;
Expand Down Expand Up @@ -111,8 +113,8 @@ Set<Expr<?>> getInputVariables() {
* Binds an identifier name in the symbol table to an already-translated value. Used to bind
* reserved policy symbols such as 'rule.result' to the composed policy graph.
*/
void bindSymbol(String varName, TranslatedValue value) {
context.bindSymbol(varName, value);
void bindSymbol(String varName, TranslatedValue value, CelAbstractSyntaxTree ast) {
context.bindSymbol(varName, value, ast);
}

TranslatedValue translate(CelAbstractSyntaxTree ast) {
Expand Down Expand Up @@ -439,6 +441,15 @@ private TranslatedValue translateCall(CelExpr expr, CelAbstractSyntaxTree ast) {
long exprId = expr.id();
String functionName = call.function();
ImmutableList<CelExpr> argsAst = call.args();
if (functionName.equals(Operator.OPTIONAL_SELECT.getFunction())) {
checkArgument(
!call.target().isPresent()
&& argsAst.size() == 2
&& argsAst.get(1).constantOrDefault().getKind() == CelConstant.Kind.STRING_VALUE,
"Malformed AST: operator %s expects an operand and a field name",
Operator.OPTIONAL_SELECT);
return structTranslator.translateSelect(expr, ast);
}

List<TranslatedValue> args = new ArrayList<>();

Expand All @@ -453,42 +464,41 @@ private TranslatedValue translateCall(CelExpr expr, CelAbstractSyntaxTree ast) {

return operatorTranslator
.translateFunctionCall(functionName, args, exprId, ast)
.map(
tv -> {
if (mayEmbedArgs(functionName, ast.getTypeOrThrow(exprId))) {
propagateTruncatedTypeConstraint(
tv.z3Expr(), Iterables.transform(args, TranslatedValue::z3Expr));
}
return TranslatedValue.create(tv.z3Expr(), expr, typeSystem, tv.isApproximate());
})
.orElseGet(
() -> {
// Uninterpreted function
Sort[] argSorts = new Sort[args.size()];
Arrays.fill(argSorts, 0, args.size(), typeSystem.celValueSort());
FuncDecl<?> funcDecl =
typeSystem.internFuncDecl(
uninterpretedFunctionSymbol(exprId, ast),
argSorts,
typeSystem.celValueSort());

Expr<?>[] exprArgs = args.stream().map(TranslatedValue::z3Expr).toArray(Expr[]::new);
Expr<?> callRes = ctx.mkApp(funcDecl, exprArgs);
context.addConstraint(
typeConstraintGenerator.createTypeConstraint(callRes, exprId, ast));
context.addConstraint(ctx.mkNot(typeSystem.isUnknown(callRes)));
context.addConstraint(ctx.mkNot(typeSystem.isError(callRes)));

// The solver picks the result freely, so a model depending on it is never exact.
return TranslatedValue.propagateStrict(
ctx,
typeSystem,
functionName,
callRes,
Optional.of(expr),
/* baseTaint= */ context.recordCallApproximation(functionName, ctx.mkTrue()),
args);
});
.map(tv -> {
if (mayEmbedArgs(functionName, ast.getTypeOrThrow(exprId))) {
propagateTruncatedTypeConstraint(
tv.z3Expr(), Iterables.transform(args, TranslatedValue::z3Expr));
}
return TranslatedValue.create(tv.z3Expr(), expr, typeSystem, tv.isApproximate());
})
.orElseGet(() -> {
// Uninterpreted function
Sort[] argSorts = new Sort[args.size()];
Arrays.fill(argSorts, 0, args.size(), typeSystem.celValueSort());
FuncDecl<?> funcDecl =
typeSystem.internFuncDecl(
uninterpretedFunctionSymbol(exprId, ast), argSorts, typeSystem.celValueSort());

Expr<?>[] exprArgs = args.stream().map(TranslatedValue::z3Expr).toArray(Expr[]::new);
Expr<?> callRes = ctx.mkApp(funcDecl, exprArgs);
// A narrowed result's static type doesn't constrain it.
if (!context.mayBeNarrowed(expr, ast)) {
context.addConstraint(
typeConstraintGenerator.createTypeConstraint(callRes, exprId, ast));
}
context.addConstraint(ctx.mkNot(typeSystem.isUnknown(callRes)));
context.addConstraint(ctx.mkNot(typeSystem.isError(callRes)));

// The solver picks the result freely, so a model depending on it is never exact.
return TranslatedValue.propagateStrict(
ctx,
typeSystem,
functionName,
callRes,
Optional.of(expr),
/* baseTaint= */ context.recordCallApproximation(functionName, ctx.mkTrue()),
args);
});
}

/**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,10 @@
/** Factory class for producing policy verifiers. */
public final class CelPolicyVerifierFactory {

/** Create a new {@link CelPolicyVerifierBuilder} instance. */
/**
* Create a new {@link CelPolicyVerifierBuilder} instance. {@code astVerifier} must be built from
* the same {@code Cel} environment as {@code compiler}.
*/
public static CelPolicyVerifierBuilder newVerifier(
CelPolicyCompiler compiler, CelVerifier astVerifier) {
return CelPolicyVerifierImpl.newBuilder(compiler, astVerifier);
Expand Down
28 changes: 17 additions & 11 deletions verifier/src/main/java/dev/cel/verifier/CelVerifierBuilder.java
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,6 @@
package dev.cel.verifier;

import com.google.errorprone.annotations.CanIgnoreReturnValue;
import dev.cel.common.types.CelTypeProvider;
import java.time.Duration;

/** Interface for building an instance of CelVerifier. */
Expand All @@ -41,16 +40,6 @@ public interface CelVerifierBuilder {
@CanIgnoreReturnValue
CelVerifierBuilder addUnknownIdentifier(String identifier);

/**
* Sets the type provider for looking up {@code CelType} definitions by name.
*
* <p>The verifier uses this to resolve structural type definitions (such as protocol buffer
* messages) during verification. If not set, the verifier will fall back to type information
* present in the AST, which may lose details such as wrapper types.
*/
@CanIgnoreReturnValue
CelVerifierBuilder setTypeProvider(CelTypeProvider typeProvider);

/**
* Sets the unroll limit for comprehensions (such as {@code map}, {@code filter}, {@code all},
* {@code exists}).
Expand Down Expand Up @@ -82,6 +71,23 @@ public interface CelVerifierBuilder {
@CanIgnoreReturnValue
CelVerifierBuilder setComprehensionUnrollLimit(int unrollLimit);

/**
* Checks the inputs the solver finds by evaluating them with the CEL runtime of the verifier's
* environment (off by default). For now this only validates them, without refining the solver
* (counterexample-guided abstraction refinement, CEGAR). An {@code INCONCLUSIVE} counterexample
* or satisfying input that the runtime confirms becomes {@code VIOLATED} (or {@code VERIFIED} for
* satisfiability), and any counterexample or satisfying input it disagrees with becomes {@code
* INCONCLUSIVE}.
*
* <p>Inputs are checked only when all their values are exact and no unknown identifiers are
* registered. When the runtime can't evaluate them, e.g. a function has no binding, the message
* says why. The runtime must follow the CEL spec (e.g. {@code CelOptions.DEFAULT}, which has no
* iteration limit), and a function with bindings must have one for each overload, which is
* synchronous, deterministic and doesn't throw.
*/
@CanIgnoreReturnValue
CelVerifierBuilder enableCegar(boolean value);

/** Builds the {@link CelVerifier} instance. */
CelVerifier build();
}
Expand Down
12 changes: 2 additions & 10 deletions verifier/src/main/java/dev/cel/verifier/CelVerifierFactory.java
Original file line number Diff line number Diff line change
Expand Up @@ -26,17 +26,9 @@
public final class CelVerifierFactory {

/**
* Create a builder for configuring a {@link CelVerifier}.
*
* @deprecated Prefer passing a {@link Cel} environment using {@link #newVerifier(Cel)} to enable
* canonicalization and expression re-typechecking during verification.
* Create a builder for configuring a {@link CelVerifier} with a CEL environment. The ASTs to
* verify must be compiled in {@code cel}.
*/
@Deprecated
public static CelVerifierBuilder newVerifier() {
return CelVerifierZ3Impl.newBuilder();
}

/** Create a builder for configuring a {@link CelVerifier} with a CEL environment. */
public static CelVerifierBuilder newVerifier(Cel cel) {
return CelVerifierZ3Impl.newBuilder(cel);
}
Expand Down
Loading
Loading