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
12 changes: 8 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,13 @@ 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:map_keys",
"//common/internal:proto_time_utils",
"//common/internal:well_known_proto",
"//common/types",
"//common/types:cel_types",
"//common/types:type_providers",
Expand All @@ -198,10 +199,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
Original file line number Diff line number Diff line change
Expand Up @@ -243,7 +243,7 @@ private TranslatedValue translateIdent(CelExpr celExpr, CelAbstractSyntaxTree as
}
String name = ident.name();
CelType type = ast.getTypeOrThrow(exprId);
if (type instanceof TypeType) {
if (type instanceof TypeType && !context.lookupSymbol(name).isPresent()) {
TypeType typeType = (TypeType) type;
if (typeType.type().kind() != CelKind.DYN) {
return TranslatedValue.create(
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
41 changes: 25 additions & 16 deletions verifier/src/main/java/dev/cel/verifier/CelVerificationResult.java
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,6 @@
package dev.cel.verifier;

import com.google.auto.value.AutoValue;
import java.util.Map;
import java.util.Optional;

/** Result object containing the outcome of a CEL AST verification check. */
Expand All @@ -41,13 +40,14 @@ public enum VerificationStatus {
public abstract String reason();

/**
* Returns a detailed counterexample or satisfying model assignment, if one was found.
* Returns a detailed counterexample or satisfying model assignment, if one was found, or the
* input the CEL runtime refuted.
*/
public abstract String counterexample();

/**
* Returns the counterexample or satisfying input found by the solver, if any. Its variables are
* empty when the outcome doesn't depend on any input.
* Returns the counterexample or satisfying input found by the solver, if any, or the input the
* CEL runtime refuted. Its variables are empty when the outcome doesn't depend on any input.
*/
public abstract Optional<CelWitness> witness();

Expand Down Expand Up @@ -87,6 +87,14 @@ static CelVerificationResult inconclusive(
return create(VerificationStatus.INCONCLUSIVE, reason, witness, isCounterexample);
}

static CelVerificationResult refuted(String reason, CelWitness witness) {
return new AutoValue_CelVerificationResult(
VerificationStatus.INCONCLUSIVE,
reason,
witness.variables().isEmpty() ? "" : listInputs(" Input found:", witness),
Optional.of(witness));
}

private static CelVerificationResult create(VerificationStatus status, String reason) {
return new AutoValue_CelVerificationResult(status, reason, "", Optional.empty());
}
Expand All @@ -108,18 +116,19 @@ private static String describe(
: " (The expression is satisfiable unconditionally, regardless of input state)";
}

StringBuilder sb = new StringBuilder();
if (isCounterexample) {
sb.append(isApproximate ? " Potential counterexample input:" : " Counterexample input:");
} else {
sb.append(isApproximate ? " Potential satisfying input:" : " Satisfying input:");
}
for (Map.Entry<String, CelWitness.Variable> variable : witness.variables().entrySet()) {
sb.append("\n ")
.append(variable.getKey())
.append(" = ")
.append(variable.getValue().displayValue());
}
return listInputs(
isCounterexample
? (isApproximate ? " Potential counterexample input:" : " Counterexample input:")
: (isApproximate ? " Potential satisfying input:" : " Satisfying input:"),
witness);
}

private static String listInputs(String label, CelWitness witness) {
StringBuilder sb = new StringBuilder(label);
witness
.variables()
.forEach((name, variable) ->
sb.append("\n ").append(name).append(" = ").append(variable.displayValue()));
return sb.toString();
}
}
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