claripy — Solver Engine

Realistically, you should never have to work with in-depth claripy APIs unless you’re doing some hard-core analysis. Most of the time, you’ll be using claripy as a simple frontend to z3:

import claripy
a = claripy.BVS("sym_val", 32)
b = claripy.RotateLeft(a, 8)
c = b + 4
s = claripy.Solver()
s.add(c == 0x41424344)
assert s.eval(c, 1)[0] == 0x41424344
assert s.eval(a, 1)[0] == 0x40414243

Or using its components in angr:

import angr, claripy
b = angr.Project('/bin/true')
path = b.factory.path()
rax_start = claripy.BVS('rax_start', 64)
path.state.regs.rax = rax_start
path_new = path.step()[0]
rax_new = path_new.state.regs.rax
path_new.state.se.add(rax_new == 1337)
print path_new.state.se.eval(rax_start, 1)[0]

AST

class claripy.ast.base.ASTCacheKey(a)

Bases: object

class claripy.ast.base.Base(op, args, add_variables=None, hash=None, **kwargs)

Bases: object

This is the base class of all claripy ASTs. An AST tracks a tree of operations on arguments.

This class should not be instanciated directly - instead, use one of the constructor functions (BVS, BVV, FPS, FPV…) to construct a leaf node and then build more complicated expressions using operations.

AST objects have hash identity. This means that an AST that has the same hash as another AST will be the same object. This is critical for efficient memory usage. As an example, the following is true:

a, b = two different ASTs
c = b + a
d = b + a
assert c is d
Variables
  • op – The operation that is being done on the arguments

  • args – The arguments that are being used

This is called when you create a new Base object, whether directly or through an operation. It finalizes the arguments (see the _finalize function, above) and then computes a hash. If an AST of this hash already exists, it returns that AST. Otherwise, it creates, initializes, and returns the AST.

Parameters
  • op – The AST operation (‘__add__’, ‘Or’, etc)

  • args – The arguments to the AST operation (i.e., the objects to add)

  • variables – The symbolic variables present in the AST (default: empty set)

  • symbolic – A flag saying whether or not the AST is symbolic (default: False)

  • length – An integer specifying the length of this AST (default: None)

  • simplified – A measure of how simplified this AST is. 0 means unsimplified, 1 means fast-simplified (basically, just undoing the Reverse op), and 2 means simplified through z3.

  • errored – A set of backends that are known to be unable to handle this AST.

  • eager_backends – A list of backends with which to attempt eager evaluation

  • annotations – A frozenset of annotations applied onto this AST.

FULL_SIMPLIFY = 1
LITE_SIMPLIFY = 2
UNSIMPLIFIED = 0
LITE_REPR = 0
MID_REPR = 1
FULL_REPR = 2
property cache_key

A key that refers to this AST - this value is appropriate for usage as a key in dictionaries.

make_like(op, args, **kwargs)
append_annotation(a)

Appends an annotation to this AST.

Parameters

a – the annotation to append

Returns

a new AST, with the annotation added

append_annotations(new_tuple)

Appends several annotations to this AST.

Parameters

new_tuple – the tuple of annotations to append

Returns

a new AST, with the annotations added

annotate(*args)

Appends annotations to this AST.

Parameters

args – the tuple of annotations to append (variadic positional args)

Returns

a new AST, with the annotations added

insert_annotation(a)

Inserts an annotation to this AST.

Parameters

a – the annotation to insert

Returns

a new AST, with the annotation added

insert_annotations(new_tuple)

Inserts several annotations to this AST.

Parameters

new_tuple – the tuple of annotations to insert

Returns

a new AST, with the annotations added

replace_annotations(new_tuple)

Replaces annotations on this AST.

Parameters

new_tuple – the tuple of annotations to replace the old annotations with

Returns

a new AST, with the annotations added

remove_annotation(a)

Removes an annotation from this AST.

Parameters

a – the annotation to remove

Returns

a new AST, with the annotation removed

remove_annotations(remove_sequence)

Removes several annotations from this AST.

Parameters

remove_sequence – a sequence/set of the annotations to remove

Returns

a new AST, with the annotations removed

dbg_repr(prefix=None)

Returns a debug representation of this AST.

shallow_repr(max_depth=8, explicit_length=False, details=0, inner=False, parent_prec=15, left=True)

Returns a string representation of this AST, but with a maximum depth to prevent floods of text being printed.

Parameters
  • max_depth – The maximum depth to print.

  • explicit_length – Print lengths of BVV arguments.

  • details – An integer value specifying how detailed the output should be: LITE_REPR - print short repr for both operations and BVs, MID_REPR - print full repr for operations and short for BVs, FULL_REPR - print full repr of both operations and BVs.

  • inner – whether or not it is an inner AST

  • parent_prec – parent operation precedence level

  • left – whether or not it is a left AST

Returns

A string representing the AST

children_asts()

Return an iterator over the nested children ASTs.

leaf_asts()

Return an iterator over the leaf ASTs.

property recursive_children_asts

Use children_asts() instead.

Type

DEPRECATED

property recursive_leaf_asts

Use leaf_asts() instead.

Type

DEPRECATED

dbg_is_looped()
swap_args(new_args, new_length=None, **kwargs)

This returns the same AST, with the arguments swapped out for new_args.

split(split_on)

Splits the AST if its operation is split_on (i.e., return all the arguments). Otherwise, return a list with just the AST.

structurally_match(o)

Structurally compares two A objects, and check if their corresponding leaves are definitely the same A object (name-wise or hash-identity wise).

Parameters

o – the other claripy A object

Returns

True/False

replace_dict(replacements, variable_set=None, leaf_operation=None)

Returns this AST with subexpressions replaced by those that can be found in replacements dict.

Parameters
  • variable_set – For optimization, ast’s without these variables are not checked for replacing.

  • replacements – A dictionary of hashes to their replacements.

  • leaf_operation – An operation that should be applied to the leaf nodes.

Returns

An AST with all instances of ast’s in replacements.

replace(old, new, variable_set=None, leaf_operation=None)

Returns this AST but with the AST ‘old’ replaced with AST ‘new’ in its subexpressions.

canonicalize(var_map=None, counter=None)
property ite_burrowed

Returns an equivalent AST that “burrows” the ITE expressions as deep as possible into the ast, for simpler printing.

property ite_excavated

Returns an equivalent AST that “excavates” the ITE expressions out as far as possible toward the root of the AST, for processing in static analyses.

property singlevalued
property multivalued
property cardinality
property concrete
property uninitialized

Whether this AST comes from an uninitialized dereference or not. It’s only used in under-constrained symbolic execution mode.

Returns

True/False/None (unspecified).

property uc_alloc_depth

The depth of allocation by lazy-initialization. It’s only used in under-constrained symbolic execution mode.

Returns

An integer indicating the allocation depth, or None if it’s not from lazy-initialization.

op
args
variables
symbolic
length
annotations
simplifiable
depth
claripy.ast.base.simplify(e)
class claripy.ast.bits.Bits(op, args, add_variables=None, hash=None, **kwargs)

Bases: claripy.ast.base.Base

A base class for AST types that can be stored as a series of bits. Currently, this is bitvectors and IEEE floats.

Variables

length – The length of this value in bits.

This is called when you create a new Base object, whether directly or through an operation. It finalizes the arguments (see the _finalize function, above) and then computes a hash. If an AST of this hash already exists, it returns that AST. Otherwise, it creates, initializes, and returns the AST.

Parameters
  • op – The AST operation (‘__add__’, ‘Or’, etc)

  • args – The arguments to the AST operation (i.e., the objects to add)

  • variables – The symbolic variables present in the AST (default: empty set)

  • symbolic – A flag saying whether or not the AST is symbolic (default: False)

  • length – An integer specifying the length of this AST (default: None)

  • simplified – A measure of how simplified this AST is. 0 means unsimplified, 1 means fast-simplified (basically, just undoing the Reverse op), and 2 means simplified through z3.

  • errored – A set of backends that are known to be unable to handle this AST.

  • eager_backends – A list of backends with which to attempt eager evaluation

  • annotations – A frozenset of annotations applied onto this AST.

length
make_like(op, args, **kwargs)
size()
raw_to_bv()

Converts this data’s bit-pattern to a bitvector.

raw_to_fp()

Converts this data’s bit-pattern to an IEEE float.

claripy.ast.bool.cleanup()
class claripy.ast.bool.Bool(op, args, add_variables=None, hash=None, **kwargs)

Bases: claripy.ast.base.Base

This is called when you create a new Base object, whether directly or through an operation. It finalizes the arguments (see the _finalize function, above) and then computes a hash. If an AST of this hash already exists, it returns that AST. Otherwise, it creates, initializes, and returns the AST.

Parameters
  • op – The AST operation (‘__add__’, ‘Or’, etc)

  • args – The arguments to the AST operation (i.e., the objects to add)

  • variables – The symbolic variables present in the AST (default: empty set)

  • symbolic – A flag saying whether or not the AST is symbolic (default: False)

  • length – An integer specifying the length of this AST (default: None)

  • simplified – A measure of how simplified this AST is. 0 means unsimplified, 1 means fast-simplified (basically, just undoing the Reverse op), and 2 means simplified through z3.

  • errored – A set of backends that are known to be unable to handle this AST.

  • eager_backends – A list of backends with which to attempt eager evaluation

  • annotations – A frozenset of annotations applied onto this AST.

is_true()

Returns True if ‘self’ can be easily determined to be True. Otherwise, return False. Note that the AST might still be True (i.e., if it were simplified via Z3), but it’s hard to quickly tell that.

is_false()

Returns True if ‘self’ can be easily determined to be False. Otherwise, return False. Note that the AST might still be False (i.e., if it were simplified via Z3), but it’s hard to quickly tell that.

intersection()
claripy.ast.bool.BoolS(name, explicit_name=None)

Creates a boolean symbol (i.e., a variable).

Parameters
  • name – The name of the symbol

  • explicit_name – If False, an identifier is appended to the name to ensure uniqueness.

Returns

A Bool object representing this symbol.

claripy.ast.bool.BoolV(val)
claripy.ast.bool.If(*args)
claripy.ast.bool.is_true(e, exact=None)
claripy.ast.bool.is_false(e, exact=None)
claripy.ast.bool.ite_dict(i, d, default)

Return an expression of if-then-else trees which expresses a switch tree :param i: The variable which may take on multiple values affecting the final result :param d: A dict mapping possible values for i to values which the result could be :param default: A default value that the expression should take on if i matches none of the keys of d :return: An expression encoding the result of the above

claripy.ast.bool.ite_cases(cases, default)

Return an expression of if-then-else trees which expresses a series of alternatives

Parameters
  • cases – A list of tuples (c, v). c is the condition under which v should be the result of the expression

  • default – A default value that the expression should take on if none of the c conditions are satisfied

Returns

An expression encoding the result of the above

claripy.ast.bool.reverse_ite_cases(ast)

Given an expression created by ite_cases, produce the cases that generated it :param ast: :return:

claripy.ast.bool.constraint_to_si(expr)

Convert a constraint to SI if possible.

Parameters

expr

Returns

claripy.ast.bv.cleanup()
class claripy.ast.bv.BV(op, args, add_variables=None, hash=None, **kwargs)

Bases: claripy.ast.bits.Bits

A class representing an AST of operations culminating in a bitvector. Do not instantiate this class directly, instead use BVS or BVV to construct a symbol or value, and then use operations to construct more complicated expressions.

Individual sub-bits and bit-ranges can be extracted from a bitvector using index and slice notation. Bits are indexed weirdly. For a 32-bit AST:

a[31] is the LEFT most bit, so it’d be the 0 in

01111111111111111111111111111111

a[0] is the RIGHT most bit, so it’d be the 0 in

11111111111111111111111111111110

a[31:30] are the two leftmost bits, so they’d be the 0s in:

00111111111111111111111111111111

a[1:0] are the two rightmost bits, so they’d be the 0s in:

11111111111111111111111111111100

This is called when you create a new Base object, whether directly or through an operation. It finalizes the arguments (see the _finalize function, above) and then computes a hash. If an AST of this hash already exists, it returns that AST. Otherwise, it creates, initializes, and returns the AST.

Parameters
  • op – The AST operation (‘__add__’, ‘Or’, etc)

  • args – The arguments to the AST operation (i.e., the objects to add)

  • variables – The symbolic variables present in the AST (default: empty set)

  • symbolic – A flag saying whether or not the AST is symbolic (default: False)

  • length – An integer specifying the length of this AST (default: None)

  • simplified – A measure of how simplified this AST is. 0 means unsimplified, 1 means fast-simplified (basically, just undoing the Reverse op), and 2 means simplified through z3.

  • errored – A set of backends that are known to be unable to handle this AST.

  • eager_backends – A list of backends with which to attempt eager evaluation

  • annotations – A frozenset of annotations applied onto this AST.

chop(bits=1)

Chops a BV into consecutive sub-slices. Obviously, the length of this BV must be a multiple of bits.

Returns

A list of smaller bitvectors, each bits in length. The first one will be the left-most (i.e. most significant) bits.

get_byte(index)

Extracts a byte from a BV, where the index refers to the byte in a big-endian order

Parameters

index – the byte to extract

Returns

An 8-bit BV

get_bytes(index, size)

Extracts several bytes from a bitvector, where the index refers to the byte in a big-endian order

Parameters
  • index – the byte index at which to start extracting

  • size – the number of bytes to extract

Returns

A BV of size size * 8

zero_extend(n)

Zero-extends the bitvector by n bits. So:

a = BVV(0b1111, 4) b = a.zero_extend(4) b is BVV(0b00001111)

sign_extend(n)

Sign-extends the bitvector by n bits. So:

a = BVV(0b1111, 4) b = a.sign_extend(4) b is BVV(0b11111111)

concat(*args)

Concatenates this bitvector with the bitvectors provided. This bitvector will be on the far-left, i.e. the most significant bits.

val_to_fp(sort, signed=True, rm=None)

Interpret this bitvector as an integer, and return the floating-point representation of that integer.

Parameters
  • sort – The sort of floating point value to return

  • signed – Optional: whether this value is a signed integer

  • rm – Optional: the rounding mode to use

Returns

An FP AST whose value is the same as this BV

raw_to_fp()

Interpret the bits of this bitvector as an IEEE754 floating point number. The inverse of this function is raw_to_bv.

Returns

An FP AST whose bit-pattern is the same as this BV

raw_to_bv()

A counterpart to FP.raw_to_bv - does nothing and returns itself.

to_bv()
static Concat(*args)
static Extract(*args)
LShR()
SDiv()
SGE()
SGT()
SLE()
SLT()
SMod()
UGE()
UGT()
ULE()
ULT()
intersection()
property reversed
union()
widen()
claripy.ast.bv.BVS(name, size, min=None, max=None, stride=None, uninitialized=False, explicit_name=None, discrete_set=False, discrete_set_max_card=None, **kwargs)

Creates a bit-vector symbol (i.e., a variable).

If you want to specify the maximum or minimum value of a normal symbol that is not part of value-set analysis, you should manually add constraints to that effect. Do not use ``min`` and ``max`` for symbolic execution.

Parameters
  • name – The name of the symbol.

  • size – The size (in bits) of the bit-vector.

  • min – The minimum value of the symbol, used only for value-set analysis

  • max – The maximum value of the symbol, used only for value-set analysis

  • stride – The stride of the symbol, used only for value-set analysis

  • uninitialized – Whether this value should be counted as an “uninitialized” value in the course of an analysis.

  • explicit_name (bool) – If False, an identifier is appended to the name to ensure uniqueness.

  • discrete_set (bool) – If True, a DiscreteStridedIntervalSet will be used instead of a normal StridedInterval.

  • discrete_set_max_card (int) – The maximum cardinality of the discrete set. It is ignored if discrete_set is set to False or None.

Returns

a BV object representing this symbol.

claripy.ast.bv.BVV(value, size=None, **kwargs)

Creates a bit-vector value (i.e., a concrete value).

Parameters
  • value – The value. Either an integer or a bytestring. If it’s the latter, it will be interpreted as the bytes of a big-endian constant.

  • size – The size (in bits) of the bit-vector. Optional if you provide a string, required for an integer.

Returns

A BV object representing this value.

claripy.ast.bv.SI(name=None, bits=0, lower_bound=None, upper_bound=None, stride=None, to_conv=None, explicit_name=None, discrete_set=False, discrete_set_max_card=None)
claripy.ast.bv.TSI(bits, name=None, uninitialized=False, explicit_name=None)
claripy.ast.bv.ESI(bits, **kwargs)
claripy.ast.bv.ValueSet(bits, region=None, region_base_addr=None, value=None, name=None, val=None)
claripy.ast.bv.VS(bits, region=None, region_base_addr=None, value=None, name=None, val=None)
claripy.ast.bv.DSIS(name=None, bits=0, lower_bound=None, upper_bound=None, stride=None, explicit_name=None, to_conv=None, max_card=None)
class claripy.ast.fp.FP(op, args, add_variables=None, hash=None, **kwargs)

Bases: claripy.ast.bits.Bits

An AST representing a set of operations culminating in an IEEE754 floating point number.

Do not instantiate this class directly, instead use FPV or FPS to construct a value or symbol, and then use operations to construct more complicated expressions.

Variables
  • length – The length of this value

  • sort – The sort of this value, usually either FSORT_FLOAT or FSORT_DOUBLE

This is called when you create a new Base object, whether directly or through an operation. It finalizes the arguments (see the _finalize function, above) and then computes a hash. If an AST of this hash already exists, it returns that AST. Otherwise, it creates, initializes, and returns the AST.

Parameters
  • op – The AST operation (‘__add__’, ‘Or’, etc)

  • args – The arguments to the AST operation (i.e., the objects to add)

  • variables – The symbolic variables present in the AST (default: empty set)

  • symbolic – A flag saying whether or not the AST is symbolic (default: False)

  • length – An integer specifying the length of this AST (default: None)

  • simplified – A measure of how simplified this AST is. 0 means unsimplified, 1 means fast-simplified (basically, just undoing the Reverse op), and 2 means simplified through z3.

  • errored – A set of backends that are known to be unable to handle this AST.

  • eager_backends – A list of backends with which to attempt eager evaluation

  • annotations – A frozenset of annotations applied onto this AST.

to_fp(sort, rm=None)

Convert this float to a different sort

Parameters
  • sort – The sort to convert to

  • rm – Optional: The rounding mode to use

Returns

An FP AST

raw_to_fp()

A counterpart to BV.raw_to_fp - does nothing and returns itself.

raw_to_bv()

Interpret the bit-pattern of this IEEE754 floating point number as a bitvector. The inverse of this function is to_bv.

Returns

A BV AST whose bit-pattern is the same as this FP

to_bv()
val_to_bv(size, signed=True, rm=None)

Convert this floating point value to an integer.

Parameters
  • size – The size of the bitvector to return

  • signed – Optional: Whether the target integer is signed

  • rm – Optional: The rounding mode to use

Returns

A bitvector whose value is the rounded version of this FP’s value

property sort
isInf()
isNaN()
claripy.ast.fp.FPS(name, sort, explicit_name=None)

Creates a floating-point symbol.

Parameters
  • name – The name of the symbol

  • sort – The sort of the floating point

  • explicit_name – If False, an identifier is appended to the name to ensure uniqueness.

Returns

An FP AST.

claripy.ast.fp.FPV(value, sort)

Creates a concrete floating-point value.

Parameters
  • value – The value of the floating point.

  • sort – The sort of the floating point.

Returns

An FP AST.

class claripy.ast.int.Int(op, args, add_variables=None, hash=None, **kwargs)

Bases: claripy.ast.base.Base

This is called when you create a new Base object, whether directly or through an operation. It finalizes the arguments (see the _finalize function, above) and then computes a hash. If an AST of this hash already exists, it returns that AST. Otherwise, it creates, initializes, and returns the AST.

Parameters
  • op – The AST operation (‘__add__’, ‘Or’, etc)

  • args – The arguments to the AST operation (i.e., the objects to add)

  • variables – The symbolic variables present in the AST (default: empty set)

  • symbolic – A flag saying whether or not the AST is symbolic (default: False)

  • length – An integer specifying the length of this AST (default: None)

  • simplified – A measure of how simplified this AST is. 0 means unsimplified, 1 means fast-simplified (basically, just undoing the Reverse op), and 2 means simplified through z3.

  • errored – A set of backends that are known to be unable to handle this AST.

  • eager_backends – A list of backends with which to attempt eager evaluation

  • annotations – A frozenset of annotations applied onto this AST.

class claripy.ast.strings.String(op, args, add_variables=None, hash=None, **kwargs)

Bases: claripy.ast.bits.Bits

Base class that represent the AST of a String object and implements all the operation useful to create and modify the AST.

Do not instantiate this class directly, instead use StringS or StringV to construct a symbol or value, and then use operations to construct more complicated expressions.

This is called when you create a new Base object, whether directly or through an operation. It finalizes the arguments (see the _finalize function, above) and then computes a hash. If an AST of this hash already exists, it returns that AST. Otherwise, it creates, initializes, and returns the AST.

Parameters
  • op – The AST operation (‘__add__’, ‘Or’, etc)

  • args – The arguments to the AST operation (i.e., the objects to add)

  • variables – The symbolic variables present in the AST (default: empty set)

  • symbolic – A flag saying whether or not the AST is symbolic (default: False)

  • length – An integer specifying the length of this AST (default: None)

  • simplified – A measure of how simplified this AST is. 0 means unsimplified, 1 means fast-simplified (basically, just undoing the Reverse op), and 2 means simplified through z3.

  • errored – A set of backends that are known to be unable to handle this AST.

  • eager_backends – A list of backends with which to attempt eager evaluation

  • annotations – A frozenset of annotations applied onto this AST.

STRING_TYPE_IDENTIFIER = 'STRING_'
GENERATED_BVS_IDENTIFIER = 'BVS_'
MAX_LENGTH = 10000
string_length
strReplace(str_to_replace, replacement)

Replace the first occurence of str_to_replace with replacement

Parameters
  • str_to_replace (claripy.ast.String) – pattern that has to be replaced

  • replacement (claripy.ast.String) – replacement pattern

toInt(bitlength)

Convert the string to a bitvector holding the integer representation of the string

Parameters

bitlength – size of the biitvector holding the result

indexOf(pattern, start_idx, bitlength)

Return the start index of the pattern inside the input string in a Bitvector representation, otherwise it returns -1 (always using a BitVector)

Parameters

bitlength – size of the biitvector holding the result

raw_to_bv()

A counterpart to FP.raw_to_bv - does nothing and returns itself.

raw_to_fp()
static IntToStr(*args)
static StrConcat(*args)
static StrContains(*args)
static StrExtract(*args)
static StrIndexOf(*args)
static StrIsDigit(*args)
static StrLen(*args)
static StrPrefixOf(*args)
static StrReplace(*args)
static StrSubstr(*args)
static StrSuffixOf(*args)
static StrToInt(*args)
static UnitStr(*args)
claripy.ast.strings.StringS(name, size, uninitialized=False, explicit_name=False, **kwargs)

Create a new symbolic string (analogous to z3.String())

Parameters
  • name – The name of the symbolic string (i. e. the name of the variable)

  • size – The size in bytes of the string (i. e. the length of the string)

  • uninitialized – Whether this value should be counted as an “uninitialized” value in the course of an analysis.

  • explicit_name (bool) – If False, an identifier is appended to the name to ensure uniqueness.

Returns

The String object representing the symbolic string

claripy.ast.strings.StringV(value, length=None, **kwargs)

Create a new Concrete string (analogous to z3.StringVal())

Parameters

value – The constant value of the concrete string

Returns

The String object representing the concrete string

class claripy.ast.vs.VS(op, args, add_variables=None, hash=None, **kwargs)

Bases: claripy.ast.bits.Bits

This is called when you create a new Base object, whether directly or through an operation. It finalizes the arguments (see the _finalize function, above) and then computes a hash. If an AST of this hash already exists, it returns that AST. Otherwise, it creates, initializes, and returns the AST.

Parameters
  • op – The AST operation (‘__add__’, ‘Or’, etc)

  • args – The arguments to the AST operation (i.e., the objects to add)

  • variables – The symbolic variables present in the AST (default: empty set)

  • symbolic – A flag saying whether or not the AST is symbolic (default: False)

  • length – An integer specifying the length of this AST (default: None)

  • simplified – A measure of how simplified this AST is. 0 means unsimplified, 1 means fast-simplified (basically, just undoing the Reverse op), and 2 means simplified through z3.

  • errored – A set of backends that are known to be unable to handle this AST.

  • eager_backends – A list of backends with which to attempt eager evaluation

  • annotations – A frozenset of annotations applied onto this AST.

Backends

class claripy.backends.Backend(solver_required=None)

Bases: object

Backends are Claripy’s workhorses. Claripy exposes ASTs (claripy.ast.Base objects) to the world, but when actual computation has to be done, it pushes those ASTs into objects that can be handled by the backends themselves. This provides a unified interface to the outside world while allowing Claripy to support different types of computation. For example, BackendConcrete provides computation support for concrete bitvectors and booleans, BackendVSA introduces VSA constructs such as StridedIntervals (and details what happens when operations are performed on them), and BackendZ3 provides support for symbolic variables and constraint solving.

There are a set of functions that a backend is expected to implement. For all of these functions, the “public” version is expected to be able to deal with claripy.ast.Base objects, while the “private” version should only deal with objects specific to the backend itself. This is distinguished with Python idioms: a public function will be named func() while a private function will be _func(). All functions should return objects that are usable by the backend in its private methods. If this can’t be done (i.e., some functionality is being attempted that the backend can’t handle), the backend should raise a BackendError. In this case, Claripy will move on to the next backend in its list.

All backends must implement a convert() function. This function receives a claripy.ast.Base and should return an object that the backend can handle in its private methods. Backends should also implement a _convert() method, which will receive anything that is not a claripy.ast.Base object (i.e., an integer or an object from a different backend). If convert() or _convert() receives something that the backend can’t translate to a format that is usable internally, the backend should raise BackendError, and thus won’t be used for that object.

Claripy contract with its backends is as follows: backends should be able to can handle, in their private functions, any object that they return from their private or public functions. Likewise, Claripy will never pass an object to any backend private function that did not originate as a return value from a private or public function of that backend. One exception to this is _convert(), as Claripy can try to stuff anything it feels like into _convert() to see if the backend can handle that type of object.

property is_smt_backend
downsize()

Clears all caches associated with this backend.

handles(expr)

Checks whether this backend can handle the expression.

Parameters

expr – The expression.

Returns

True if the backend can handle this expression, False if not.

convert(expr)

Resolves a claripy.ast.Base into something usable by the backend.

Parameters
  • expr – The expression.

  • save – Save the result in the expression’s object cache

Returns

A backend object.

convert_list(args)
call(op, args)

Calls operation op on args args with this backend.

Returns

A backend object representing the result.

simplify(e)
is_true(e, extra_constraints=(), solver=None, model_callback=None)

Should return True if e can be easily found to be True.

Parameters
  • e – The AST.

  • extra_constraints – Extra constraints (as ASTs) to add to the solver for this solve.

  • solver – A solver, for backends that require it.

  • model_callback – a function that will be executed with recovered models (if any)

Returns

A boolean.

is_false(e, extra_constraints=(), solver=None, model_callback=None)

Should return True if e can be easily found to be False.

Parameters
  • e – The AST

  • extra_constraints – Extra constraints (as ASTs) to add to the solver for this solve.

  • solver – A solver, for backends that require it

  • model_callback – a function that will be executed with recovered models (if any)

Returns

A boolean.

has_true(e, extra_constraints=(), solver=None, model_callback=None)

Should return True if e can possible be True.

Parameters
  • e – The AST.

  • extra_constraints – Extra constraints (as ASTs) to add to the solver for this solve.

  • solver – A solver, for backends that require it.

  • model_callback – a function that will be executed with recovered models (if any)

Returns

A boolean

has_false(e, extra_constraints=(), solver=None, model_callback=None)

Should return False if e can possibly be False.

Parameters
  • e – The AST.

  • extra_constraints – Extra constraints (as ASTs) to add to the solver for this solve.

  • solver – A solver, for backends that require it.

  • model_callback – a function that will be executed with recovered models (if any)

Returns

A boolean.

solver(timeout=None)

This function should return an instance of whatever object handles solving for this backend. For example, in Z3, this would be z3.Solver().

add(s, c, track=False)

This function adds constraints to the backend solver.

Parameters
  • c – A sequence of ASTs

  • s – A backend solver object

  • track (bool) – True to enable constraint tracking, which is used in unsat_core()

unsat_core(s)

This function returns the unsat core from the backend solver.

Parameters

s – A backend solver object.

Returns

The unsat core.

eval(expr, n, extra_constraints=(), solver=None, model_callback=None)

This function returns up to n possible solutions for expression expr.

Parameters
  • expr – expression (an AST) to evaluate

  • n – number of results to return

  • solver – a solver object, native to the backend, to assist in the evaluation (for example, a z3.Solver)

  • extra_constraints – extra constraints (as ASTs) to add to the solver for this solve

  • model_callback – a function that will be executed with recovered models (if any)

Returns

A sequence of up to n results (backend objects)

batch_eval(exprs, n, extra_constraints=(), solver=None, model_callback=None)

Evaluate one or multiple expressions.

Parameters
  • exprs – A list of expressions to evaluate.

  • n – Number of different solutions to return.

  • extra_constraints – Extra constraints (as ASTs) to add to the solver for this solve.

  • solver – A solver object, native to the backend, to assist in the evaluation.

  • model_callback – a function that will be executed with recovered models (if any)

Returns

A list of up to n tuples, where each tuple is a solution for all expressions.

min(expr, extra_constraints=(), solver=None, model_callback=None)

Return the minimum value of expr.

Parameters
  • expr – expression (an AST) to evaluate

  • solver – a solver object, native to the backend, to assist in the evaluation (for example, a z3.Solver)

  • extra_constraints – extra constraints (as ASTs) to add to the solver for this solve

  • model_callback – a function that will be executed with recovered models (if any)

Returns

the minimum possible value of expr (backend object)

max(expr, extra_constraints=(), solver=None, model_callback=None)

Return the maximum value of expr.

Parameters
  • expr – expression (an AST) to evaluate

  • solver – a solver object, native to the backend, to assist in the evaluation (for example, a z3.Solver)

  • extra_constraints – extra constraints (as ASTs) to add to the solver for this solve

  • model_callback – a function that will be executed with recovered models (if any)

Returns

the maximum possible value of expr (backend object)

check_satisfiability(extra_constraints=(), solver=None, model_callback=None)

This function does a constraint check and returns the solvers state

Parameters
  • solver – The backend solver object.

  • extra_constraints – Extra constraints (as ASTs) to add to s for this solve

  • model_callback – a function that will be executed with recovered models (if any)

Returns

‘SAT’, ‘UNSAT’, or ‘UNKNOWN’

satisfiable(extra_constraints=(), solver=None, model_callback=None)

This function does a constraint check and checks if the solver is in a sat state.

Parameters
  • solver – The backend solver object.

  • extra_constraints – Extra constraints (as ASTs) to add to s for this solve

  • model_callback – a function that will be executed with recovered models (if any)

Returns

True if sat, otherwise false

solution(expr, v, extra_constraints=(), solver=None, model_callback=None)

Return True if v is a solution of expr with the extra constraints, False otherwise.

Parameters
  • expr – An expression (an AST) to evaluate

  • v – The proposed solution (an AST)

  • solver – A solver object, native to the backend, to assist in the evaluation (for example, a z3.Solver).

  • extra_constraints – Extra constraints (as ASTs) to add to the solver for this solve.

  • model_callback – a function that will be executed with recovered models (if any)

Returns

True if v is a solution of expr, False otherwise

name(a)

This should return the name of an expression.

Parameters

a – the AST to evaluate

identical(a, b)

This should return whether a is identical to b. Of course, this isn’t always clear. True should mean that it is definitely identical. False eans that, conservatively, it might not be.

Parameters
  • a – an AST

  • b – another AST

cardinality(a)

This should return the maximum number of values that an expression can take on. This should be a strict over approximation.

Parameters

a – The AST to evaluate

Returns

An integer

singlevalued(a)
multivalued(a)
apply_annotation(o, a)

This should apply the annotation on the backend object, and return a new backend object.

Parameters
  • o – A backend object.

  • a – An Annotation object.

Returns

A backend object.

default_op(expr)
class claripy.backend_manager.BackendManager

Bases: object

downsize()
class claripy.backend_object.BackendObject

Bases: object

This is a base class for custom backend objects to implement.

It lets Claripy know that how to deal with those objects, in case they’re directly used in operations.

Backend objects that don’t derive from this class need to be wrapped in a type-I claripy.ast.Base.

to_claripy()

Claripy calls this to retrieve something that it can directly reason about.

class claripy.backends.backend_concrete.BackendConcrete

Bases: claripy.backends.Backend

static BVV(value, size)
static StringV(value, size)
static FPV(op, sort)
convert(expr)

Override Backend.convert() to add fast paths for BVVs and BoolVs.

is_true(e, extra_constraints=(), solver=None, model_callback=None)
is_false(e, extra_constraints=(), solver=None, model_callback=None)
claripy.backends.backend_z3.z3_expr_to_smt2(f, status='unknown', name='benchmark', logic='')
claripy.backends.backend_z3.claripy_solver_to_smt2(s)
claripy.backends.backend_z3.condom(f)
class claripy.backends.backend_z3.SmartLRUCache(maxsize, getsizeof=None, evict=None)

Bases: cachetools.lru.LRUCache

popitem()
class claripy.backends.backend_z3.BackendZ3(reuse_z3_solver=None, ast_cache_size=10000)

Bases: claripy.backends.Backend

property extra_bvs_data
downsize()
BVS(**kwargs)

The Z3 condom intercepts Z3Exceptions and throws a ClaripyZ3Error instead.

BVV(**kwargs)

The Z3 condom intercepts Z3Exceptions and throws a ClaripyZ3Error instead.

FPS(**kwargs)

The Z3 condom intercepts Z3Exceptions and throws a ClaripyZ3Error instead.

FPV(**kwargs)

The Z3 condom intercepts Z3Exceptions and throws a ClaripyZ3Error instead.

BoolS(**kwargs)

The Z3 condom intercepts Z3Exceptions and throws a ClaripyZ3Error instead.

BoolV(**kwargs)

The Z3 condom intercepts Z3Exceptions and throws a ClaripyZ3Error instead.

StringV(**kwargs)

The Z3 condom intercepts Z3Exceptions and throws a ClaripyZ3Error instead.

StringS(**kwargs)

The Z3 condom intercepts Z3Exceptions and throws a ClaripyZ3Error instead.

call(*args, **kwargs)
solver(timeout=None)
add(s, c, track=False)
simplify(**kwargs)

The Z3 condom intercepts Z3Exceptions and throws a ClaripyZ3Error instead.

class claripy.backends.backend_z3_parallel.BackendZ3Parallel

Bases: claripy.backends.backend_z3.BackendZ3

abstract(*args, **kwargs)
solver(*args, **kwargs)
call(*args, **kwargs)
resolve(*args, **kwargs)
simplify(*args, **kwargs)
claripy.backends.backend_vsa.arg_filter(f)
claripy.backends.backend_vsa.normalize_arg_order(f)
claripy.backends.backend_vsa.convert_args(f)
class claripy.backends.backend_vsa.BackendVSA

Bases: claripy.backends.Backend

convert(expr)
simplify(e)
name(a)
apply_annotation(bo, annotation)

Apply an annotation on the backend object.

Parameters
Returns

A new BackendObject

Return type

BackendObject

BVV(ast)
static BoolV(ast)
static And(a, *args)
static Not(a)
static ULT(a, b)
static ULE(a, b)
static UGT(a, b)
static UGE(a, b)
static SLT(a, b)
static SLE(a, b)
static SGT(a, b)
static SGE(a, b)
static BVS(ast)
If(cond, t, f)
static Or(*args)
static LShR(expr, shift_amount)
static Concat(*args)
static Extract(*args)
static SignExt(*args)
static ZeroExt(*args)
static Reverse(arg)
union(ast)
intersection(ast)
widen(ast)
static CreateTopStridedInterval(bits, name=None, uninitialized=False)
constraint_to_si(expr)
static CreateStridedInterval(name=None, bits=0, stride=None, lower_bound=None, upper_bound=None, uninitialized=False, to_conv=None, discrete_set=False, discrete_set_max_cardinality=None)
Parameters
  • name

  • bits

  • stride

  • lower_bound

  • upper_bound

  • to_conv

  • discrete_set (bool) –

  • discrete_set_max_cardinality (int) –

Returns

claripy.backends.backend_smtlib_solvers.z3str_popen.get_version()
class claripy.backends.backend_smtlib_solvers.z3str_popen.Z3StrProxy(timeout=None)

Bases: claripy.backends.backend_smtlib_solvers.PopenSolverProxy

create_process()
class claripy.backends.backend_smtlib_solvers.z3str_popen.SolverBackendZ3Str(*args, **kwargs)

Bases: claripy.backends.backend_smtlib_solvers.SMTLibSolverBackend

solver(timeout=None)

This function should return an instance of whatever object handles solving for this backend. For example, in Z3, this would be z3.Solver().

claripy.backends.backend_smtlib_solvers.cvc4_popen.get_version()
class claripy.backends.backend_smtlib_solvers.cvc4_popen.CVC4Proxy(timeout=None)

Bases: claripy.backends.backend_smtlib_solvers.PopenSolverProxy

create_process()
class claripy.backends.backend_smtlib_solvers.cvc4_popen.SolverBackendCVC4(*args, **kwargs)

Bases: claripy.backends.backend_smtlib_solvers.SMTLibSolverBackend

solver(timeout=None)

This function should return an instance of whatever object handles solving for this backend. For example, in Z3, this would be z3.Solver().

claripy.backends.backend_smtlib_solvers.z3_popen.get_version()
class claripy.backends.backend_smtlib_solvers.z3_popen.Z3Proxy(timeout=None)

Bases: claripy.backends.backend_smtlib_solvers.PopenSolverProxy

create_process()
class claripy.backends.backend_smtlib_solvers.z3_popen.SolverBackendZ3(*args, **kwargs)

Bases: claripy.backends.backend_smtlib_solvers.SMTLibSolverBackend

solver(timeout=None)

This function should return an instance of whatever object handles solving for this backend. For example, in Z3, this would be z3.Solver().

claripy.backends.backend_smtlib_solvers.abc_popen.get_version()
class claripy.backends.backend_smtlib_solvers.abc_popen.ABCProxy

Bases: claripy.backends.backend_smtlib_solvers.PopenSolverProxy

create_process()
class claripy.backends.backend_smtlib_solvers.abc_popen.SolverBackendABC(*args, **kwargs)

Bases: claripy.backends.backend_smtlib_solvers.SMTLibSolverBackend

solver(timeout=None)

This function should return an instance of whatever object handles solving for this backend. For example, in Z3, this would be z3.Solver().

class claripy.backends.backend_smtlib_solvers.AbstractSMTLibSolverProxy

Bases: object

write(smt)
read(n)
setup()
reset()
readuntil(s)
readline()
writeline(l)
read_sat()
read_model()
create_process()
class claripy.backends.backend_smtlib_solvers.PopenSolverProxy(p)

Bases: claripy.backends.backend_smtlib_solvers.AbstractSMTLibSolverProxy

read(n)
write(smt)
add_constraints(csts, track=False)
terminate()
class claripy.backends.backend_smtlib_solvers.SMTLibSolverBackend(*args, **kwargs)

Bases: claripy.backends.backend_smtlib.BackendSMTLibBase

solver(timeout=None)

This function should return an instance of whatever object handles solving for this backend. For example, in Z3, this would be z3.Solver().

eval(expr, n, extra_constraints=(), solver=None, model_callback=None)

This function returns up to n possible solutions for expression expr.

Parameters
  • expr – expression (an AST) to evaluate

  • n – number of results to return

  • solver – a solver object, native to the backend, to assist in the evaluation (for example, a z3.Solver)

  • extra_constraints – extra constraints (as ASTs) to add to the solver for this solve

  • model_callback – a function that will be executed with recovered models (if any)

Returns

A sequence of up to n results (backend objects)

class claripy.backends.backend_smtlib.BackendSMTLibBase(*args, **kwargs)

Bases: claripy.backends.Backend

property is_smt_backend
StringV(ast)
StringS(ast)
BoolV(ast)
BoolS(ast)
BVV(ast)
BVS(ast)

Frontends

class claripy.frontend.Frontend

Bases: object

branch()
blank_copy()
eval_to_ast(e, n, extra_constraints=(), exact=None)

Evaluates expression e, returning a list of n concrete ASTs.

Parameters
  • e – the expression

  • n – the number of ASTs to return

  • extra_constraints – extra constraints to consider when performing the evaluation

  • exact – whether or not to perform an exact evaluation. Ignored by non-approximating backends.

Returns

list of concrete ASTs

finalize()
merge(others, merge_conditions, common_ancestor=None)
combine(others)
split()
add(constraints)

Adds constraint(s) to constraints list.

Parameters

constraints – constraint(s) to add

Returns

simplify()

Simplifies the stored constraints conjunction.

check_satisfiability(extra_constraints=(), exact=None)

Checks the satisfiability of stored constraints conjunction.

Parameters
  • extra_constraints – extra constraints to consider when checking satisfiability

  • exact – whether or not to perform exact checking. Ignored by non-approximating backends.

Returns

‘SAT’ if the conjunction is satisfiable otherwise ‘UNSAT’

satisfiable(extra_constraints=(), exact=None)

Checks if stored constraints conjunction is satisfiable.

Parameters
  • extra_constraints – extra constraints to consider when checking satisfiability

  • exact – whether or not to perform exact checking. Ignored by non-approximating backends.

Returns

True if the conjunction is satisfiable otherwise False

eval(e, n, extra_constraints=(), exact=None)

Evaluates expression e, returning a tuple of n solutions.

Parameters
  • e – the expression

  • n – the number of solutions to return

  • extra_constraints – extra constraints to consider when performing the evaluation

  • exact – whether or not to perform an exact evaluation. Ignored by non-approximating backends.

Returns

tuple of python primitives representing results

batch_eval(exprs, n, extra_constraints=(), exact=None)

Evaluates exprs, returning a list of tuples (one tuple of n solutions for expression).

Parameters
  • exprs – expressions

  • n – the number of solutions to return

  • extra_constraints – extra constraints to consider when performing the evaluation

  • exact – whether or not to perform an exact evaluation. Ignored by non-approximating backends.

Returns

list of tuples of python primitives representing results

max(e, extra_constraints=(), exact=None)

Evaluates e, returning its max possible value.

Parameters
  • e – the expression

  • extra_constraints – extra constraints to consider when performing the evaluation

  • exact – whether or not to perform an exact evaluation. Ignored by non-approximating backends.

Returns

max possible value

min(e, extra_constraints=(), exact=None)

Evaluates e, returning its min possible value.

Parameters
  • e – the expression

  • extra_constraints – extra constraints to consider when performing the evaluation

  • exact – whether or not to perform an exact evaluation. Ignored by non-approximating backends.

Returns

min possible value

solution(e, v, extra_constraints=(), exact=None)

Checks if v is a possible solution to e.

Parameters
  • e – the expression

  • v – the value

  • extra_constraints – extra constraints to consider when performing the evaluation

  • exact – whether or not to perform an exact evaluation. Ignored by non-approximating backends.

Returns

True if it is a possible solution otherwise False

is_true(e, extra_constraints=(), exact=None)

Checks if e can only (and TRIVIALLY) evaluate to True. If this function returns True, then the expression cannot ever be False, regardless of constraints or anything else. If the expression returns False, then the expression might STILL not ever be False; it’s just that we can’t trivially prove it. In other words, a return value of False gives you no information whatsoever.

Parameters
  • e – the expression

  • extra_constraints – extra constraints to consider when performing the evaluation

  • exact – whether or not to perform an exact evaluation. Ignored by non-approximating backends.

Returns

True if it can only evaluate to True otherwise False

is_false(e, extra_constraints=(), exact=None)

Checks if e can only (and TRIVIALLY) evaluate to False. If this function returns True, then the expression cannot ever be True, regardless of constraints or anything else. If the expression returns False, then the expression might STILL not ever be True; it’s just that we can’t trivially prove it. In other words, a return value of False gives you no information whatsoever.

Parameters
  • e – the expression

  • extra_constraints – extra constraints to consider when performing the evaluation

  • exact – whether or not to perform an exact evaluation. Ignored by non-approximating backends.

Returns

True if it can only evaluate to False otherwise False

downsize()
class claripy.frontends.composite_frontend.CompositeFrontend(template_frontend, template_frontend_string, track=False, **kwargs)

Bases: claripy.frontends.constrained_frontend.ConstrainedFrontend

downsize()
property variables
add(constraints, **kwargs)
check_satisfiability(extra_constraints=(), exact=None)
satisfiable(extra_constraints=(), exact=None)
eval(e, n, extra_constraints=(), exact=None)
batch_eval(exprs, n, extra_constraints=(), exact=None)
max(e, extra_constraints=(), exact=None)
min(e, extra_constraints=(), exact=None)
solution(e, v, extra_constraints=(), exact=None)
is_true(e, extra_constraints=(), exact=None)
is_false(e, extra_constraints=(), exact=None)
unsat_core(extra_constraints=())
simplify()
finalize()
property timeout
merge(others, merge_conditions, common_ancestor=None)
combine(others)
split()
class claripy.frontends.constrained_frontend.ConstrainedFrontend

Bases: claripy.frontend.Frontend

independent_constraints()
downsize()
finalize()
merge(others, merge_conditions, common_ancestor=None)
combine(others)
split()
add(constraints)
simplify()
check_satisfiability(extra_constraints=(), exact=None)
satisfiable(extra_constraints=(), exact=None)
batch_eval(exprs, n, extra_constraints=(), exact=None)
eval(e, n, extra_constraints=(), exact=None)
min(e, extra_constraints=(), exact=None)
max(e, extra_constraints=(), exact=None)
solution(e, v, extra_constraints=(), exact=None)
is_true(e, extra_constraints=(), exact=None)
is_false(e, extra_constraints=(), exact=None)
class claripy.frontends.full_frontend.FullFrontend(solver_backend, timeout=None, track=False, **kwargs)

Bases: claripy.frontends.constrained_frontend.ConstrainedFrontend

add(constraints)
simplify()
check_satisfiability(extra_constraints=(), exact=None)
satisfiable(extra_constraints=(), exact=None)
eval(e, n, extra_constraints=(), exact=None)
batch_eval(exprs, n, extra_constraints=(), exact=None)
max(e, extra_constraints=(), exact=None)
min(e, extra_constraints=(), exact=None)
solution(e, v, extra_constraints=(), exact=None)
is_true(e, extra_constraints=(), exact=None)
is_false(e, extra_constraints=(), exact=None)
unsat_core(extra_constraints=())
downsize()
merge(others, merge_conditions, common_ancestor=None)
class claripy.frontends.hybrid_frontend.HybridFrontend(exact_frontend, approximate_frontend, approximate_first=False, **kwargs)

Bases: claripy.frontend.Frontend

property constraints
property variables
satisfiable(extra_constraints=(), exact=None)
eval_to_ast(e, n, extra_constraints=(), exact=None)
eval(e, n, extra_constraints=(), exact=None)
batch_eval(e, n, extra_constraints=(), exact=None)
max(e, extra_constraints=(), exact=None)
min(e, extra_constraints=(), exact=None)
solution(e, v, extra_constraints=(), exact=None)
is_true(e, extra_constraints=(), exact=None)
is_false(e, extra_constraints=(), exact=None)
unsat_core(extra_constraints=())
add(constraints)
combine(others)
merge(others, merge_conditions, common_ancestor=None)
simplify()
downsize()
finalize()
split()
class claripy.frontends.light_frontend.LightFrontend(solver_backend, **kwargs)

Bases: claripy.frontends.constrained_frontend.ConstrainedFrontend

eval(e, n, extra_constraints=(), exact=None)
batch_eval(exprs, n, extra_constraints=(), exact=None)
max(e, extra_constraints=(), exact=None)
min(e, extra_constraints=(), exact=None)
solution(e, v, extra_constraints=(), exact=None)
is_true(e, extra_constraints=(), exact=None)
is_false(e, extra_constraints=(), exact=None)
satisfiable(extra_constraints=(), exact=None)
merge(others, merge_conditions, common_ancestor=None)
class claripy.frontends.replacement_frontend.ReplacementFrontend(actual_frontend, allow_symbolic=None, replacements=None, replacement_cache=None, unsafe_replacement=None, complex_auto_replace=None, auto_replace=None, replace_constraints=None, **kwargs)

Bases: claripy.frontends.constrained_frontend.ConstrainedFrontend

add_replacement(old, new, invalidate_cache=True, replace=True, promote=True)
remove_replacements(old_entries)
clear_replacements()
downsize()
eval(e, n, extra_constraints=(), exact=None)
batch_eval(exprs, n, extra_constraints=(), exact=None)
max(e, extra_constraints=(), exact=None)
min(e, extra_constraints=(), exact=None)
solution(e, v, extra_constraints=(), exact=None)
is_true(e, extra_constraints=(), exact=None)
is_false(e, extra_constraints=(), exact=None)
satisfiable(extra_constraints=(), exact=None)
add(constraints, **kwargs)
class claripy.solvers.Solver(backend=<claripy.backends.backend_z3.BackendZ3 object>, **kwargs)

Bases: claripy.frontend_mixins.constraint_fixer_mixin.ConstraintFixerMixin, claripy.frontend_mixins.concrete_handler_mixin.ConcreteHandlerMixin, claripy.frontend_mixins.eager_resolution_mixin.EagerResolutionMixin, claripy.frontend_mixins.constraint_filter_mixin.ConstraintFilterMixin, claripy.frontend_mixins.constraint_deduplicator_mixin.ConstraintDeduplicatorMixin, claripy.frontend_mixins.simplify_skipper_mixin.SimplifySkipperMixin, claripy.frontend_mixins.sat_cache_mixin.SatCacheMixin, claripy.frontend_mixins.model_cache_mixin.ModelCacheMixin, claripy.frontend_mixins.constraint_expansion_mixin.ConstraintExpansionMixin, claripy.frontend_mixins.simplify_helper_mixin.SimplifyHelperMixin, claripy.frontends.full_frontend.FullFrontend

class claripy.solvers.SolverCacheless(backend=<claripy.backends.backend_z3.BackendZ3 object>, **kwargs)

Bases: claripy.frontend_mixins.constraint_fixer_mixin.ConstraintFixerMixin, claripy.frontend_mixins.concrete_handler_mixin.ConcreteHandlerMixin, claripy.frontend_mixins.eager_resolution_mixin.EagerResolutionMixin, claripy.frontend_mixins.constraint_filter_mixin.ConstraintFilterMixin, claripy.frontend_mixins.constraint_deduplicator_mixin.ConstraintDeduplicatorMixin, claripy.frontend_mixins.simplify_skipper_mixin.SimplifySkipperMixin, claripy.frontends.full_frontend.FullFrontend

class claripy.solvers.SolverReplacement(actual_frontend=None, **kwargs)

Bases: claripy.frontend_mixins.constraint_fixer_mixin.ConstraintFixerMixin, claripy.frontend_mixins.concrete_handler_mixin.ConcreteHandlerMixin, claripy.frontend_mixins.constraint_deduplicator_mixin.ConstraintDeduplicatorMixin, claripy.frontends.replacement_frontend.ReplacementFrontend

class claripy.solvers.SolverHybrid(exact_frontend=None, approximate_frontend=None, complex_auto_replace=True, replace_constraints=True, track=False, approximate_first=False, **kwargs)

Bases: claripy.frontend_mixins.constraint_fixer_mixin.ConstraintFixerMixin, claripy.frontend_mixins.concrete_handler_mixin.ConcreteHandlerMixin, claripy.frontend_mixins.eager_resolution_mixin.EagerResolutionMixin, claripy.frontend_mixins.constraint_filter_mixin.ConstraintFilterMixin, claripy.frontend_mixins.constraint_deduplicator_mixin.ConstraintDeduplicatorMixin, claripy.frontend_mixins.simplify_skipper_mixin.SimplifySkipperMixin, claripy.frontends.hybrid_frontend.HybridFrontend

class claripy.solvers.SolverVSA(**kwargs)

Bases: claripy.frontend_mixins.constraint_fixer_mixin.ConstraintFixerMixin, claripy.frontend_mixins.concrete_handler_mixin.ConcreteHandlerMixin, claripy.frontend_mixins.constraint_filter_mixin.ConstraintFilterMixin, claripy.frontends.light_frontend.LightFrontend

class claripy.solvers.SolverConcrete(**kwargs)

Bases: claripy.frontend_mixins.constraint_fixer_mixin.ConstraintFixerMixin, claripy.frontend_mixins.concrete_handler_mixin.ConcreteHandlerMixin, claripy.frontend_mixins.constraint_filter_mixin.ConstraintFilterMixin, claripy.frontends.light_frontend.LightFrontend

class claripy.solvers.SolverStrings(backend, *args, **kwargs)

Bases: claripy.frontend_mixins.constraint_fixer_mixin.ConstraintFixerMixin, claripy.frontend_mixins.concrete_handler_mixin.ConcreteHandlerMixin, claripy.frontend_mixins.constraint_filter_mixin.ConstraintFilterMixin, claripy.frontend_mixins.constraint_deduplicator_mixin.ConstraintDeduplicatorMixin, claripy.frontend_mixins.eager_resolution_mixin.EagerResolutionMixin, claripy.frontend_mixins.eval_string_to_ast_mixin.EvalStringsToASTsMixin, claripy.frontend_mixins.smtlib_script_dumper_mixin.SMTLibScriptDumperMixin, claripy.frontends.full_frontend.FullFrontend

class claripy.solvers.SolverCompositeChild(backend=<claripy.backends.backend_z3.BackendZ3 object>, **kwargs)

Bases: claripy.frontend_mixins.constraint_deduplicator_mixin.ConstraintDeduplicatorMixin, claripy.frontend_mixins.sat_cache_mixin.SatCacheMixin, claripy.frontend_mixins.simplify_skipper_mixin.SimplifySkipperMixin, claripy.frontend_mixins.model_cache_mixin.ModelCacheMixin, claripy.frontends.full_frontend.FullFrontend

class claripy.solvers.SolverComposite(template_solver=None, track=False, template_solver_string=None, **kwargs)

Bases: claripy.frontend_mixins.constraint_fixer_mixin.ConstraintFixerMixin, claripy.frontend_mixins.concrete_handler_mixin.ConcreteHandlerMixin, claripy.frontend_mixins.eager_resolution_mixin.EagerResolutionMixin, claripy.frontend_mixins.constraint_filter_mixin.ConstraintFilterMixin, claripy.frontend_mixins.constraint_deduplicator_mixin.ConstraintDeduplicatorMixin, claripy.frontend_mixins.sat_cache_mixin.SatCacheMixin, claripy.frontend_mixins.simplify_skipper_mixin.SimplifySkipperMixin, claripy.frontend_mixins.simplify_helper_mixin.SimplifyHelperMixin, claripy.frontend_mixins.constraint_expansion_mixin.ConstraintExpansionMixin, claripy.frontend_mixins.composited_cache_mixin.CompositedCacheMixin, claripy.frontends.composite_frontend.CompositeFrontend

Frontend Mixins

class claripy.frontend_mixins.composited_cache_mixin.CompositedCacheMixin(*args, **kwargs)

Bases: object

downsize()
class claripy.frontend_mixins.concrete_handler_mixin.ConcreteHandlerMixin

Bases: object

eval(e, n, **kwargs)
batch_eval(exprs, n, **kwargs)
max(e, **kwargs)
min(e, **kwargs)
solution(e, v, **kwargs)
is_true(e, **kwargs)
is_false(e, **kwargs)
class claripy.frontend_mixins.constraint_deduplicator_mixin.ConstraintDeduplicatorMixin(*args, **kwargs)

Bases: object

simplify(**kwargs)
add(constraints, **kwargs)
class claripy.frontend_mixins.constraint_expansion_mixin.ConstraintExpansionMixin

Bases: object

eval(e, n, extra_constraints=(), exact=None, **kwargs)
max(e, extra_constraints=(), exact=None, **kwargs)
min(e, extra_constraints=(), exact=None, **kwargs)
solution(e, v, extra_constraints=(), exact=None, **kwargs)
class claripy.frontend_mixins.constraint_filter_mixin.ConstraintFilterMixin

Bases: object

add(constraints, **kwargs)
satisfiable(extra_constraints=(), **kwargs)
eval(e, n, extra_constraints=(), **kwargs)
batch_eval(exprs, n, extra_constraints=(), **kwargs)
max(e, extra_constraints=(), **kwargs)
min(e, extra_constraints=(), **kwargs)
solution(e, v, extra_constraints=(), **kwargs)
is_true(e, extra_constraints=(), **kwargs)
is_false(e, extra_constraints=(), **kwargs)
class claripy.frontend_mixins.constraint_fixer_mixin.ConstraintFixerMixin

Bases: object

add(constraints, **kwargs)
class claripy.frontend_mixins.debug_mixin.DebugMixin(*args, **kwargs)

Bases: object

claripy.frontend_mixins.debug_mixin.debug_decorator(o)
class claripy.frontend_mixins.eager_resolution_mixin.EagerResolutionMixin

Bases: object

class claripy.frontend_mixins.model_cache_mixin.ModelCache(model)

Bases: object

filter(variables)
static combine(*models)
eval_ast(ast)

Eval the ast, replacing symbols by their last value in the model.

eval_constraints(constraints)

Returns whether the constraints is satisfied trivially by using the last model.

eval_list(asts)
class claripy.frontend_mixins.model_cache_mixin.ModelCacheMixin(*args, **kwargs)

Bases: object

simplify(*args, **kwargs)
add(constraints, invalidate_cache=True, **kwargs)
split()
combine(others)
update(other)

Updates this cache mixin with results discovered by the other split off one.

satisfiable(extra_constraints=(), **kwargs)
batch_eval(asts, n, extra_constraints=(), **kwargs)
eval(e, n, **kwargs)
min(e, extra_constraints=(), **kwargs)
max(e, extra_constraints=(), **kwargs)
solution(e, v, extra_constraints=(), **kwargs)
class claripy.frontend_mixins.sat_cache_mixin.SatCacheMixin(*args, **kwargs)

Bases: object

add(constraints, **kwargs)
simplify()
satisfiable(extra_constraints=(), **kwargs)
eval(e, n, extra_constraints=(), **kwargs)
batch_eval(e, n, extra_constraints=(), **kwargs)
max(e, extra_constraints=(), **kwargs)
min(e, extra_constraints=(), **kwargs)
solution(e, v, extra_constraints=(), **kwargs)
class claripy.frontend_mixins.simplify_helper_mixin.SimplifyHelperMixin

Bases: object

max(*args, **kwargs)
min(*args, **kwargs)
eval(e, n, *args, **kwargs)
batch_eval(e, n, *args, **kwargs)
class claripy.frontend_mixins.simplify_skipper_mixin.SimplifySkipperMixin(*args, **kwargs)

Bases: object

add(*args, **kwargs)
simplify(*args, **kwargs)
class claripy.frontend_mixins.solve_block_mixin.SolveBlockMixin(*args, **kwargs)

Bases: object

eval(*args, **kwargs)
batch_eval(*args, **kwargs)
min(*args, **kwargs)
max(*args, **kwargs)
satisfiable(*args, **kwargs)
solution(*args, **kwargs)
class claripy.frontend_mixins.eval_string_to_ast_mixin.EvalStringsToASTsMixin

Bases: object

eval_to_ast(e, n, extra_constraints=(), exact=None)
class claripy.frontend_mixins.smtlib_script_dumper_mixin.SMTLibScriptDumperMixin

Bases: object

get_smtlib_script_satisfiability(extra_constraints=(), extra_variables=())

Return an smt-lib script that check the satisfiability of the current constraints

Return string

smt-lib script

Annotations

class claripy.annotation.Annotation

Bases: object

Annotations are used to achieve claripy’s goal of being an arithmetic instrumentation engine. They provide a means to pass extra information to the claripy backends.

property eliminatable

Returns whether this annotation can be eliminated in a simplification.

Returns

True if eliminatable, False otherwise

property relocatable

Returns whether this annotation can be relocated in a simplification.

Returns

True if it can be relocated, false otherwise.

relocate(src, dst)

This is called when an annotation has to be relocated because of simplifications.

Consider the following case:

x = claripy.BVS(‘x’, 32) zero = claripy.BVV(0, 32).add_annotation(your_annotation) y = x + zero

Here, one of three things can happen:

  1. if your_annotation.eliminatable is True, the simplifiers will simply eliminate your_annotation along with zero and y is x will hold

  2. elif your_annotation.relocatable is False, the simplifier will abort and y will never be simplified

  3. elif your_annotation.relocatable is True, the simplifier will run, determine that the simplified result of x + zero will be x. It will then call your_annotation.relocate(zero, x) to move the annotation away from the AST that is about to be eliminated.

Parameters
  • src – the old AST that was eliminated in the simplification

  • dst – the new AST (the result of a simplification)

Returns

the annotation that will be applied to dst

class claripy.annotation.SimplificationAvoidanceAnnotation

Bases: claripy.annotation.Annotation

property eliminatable
property relocatable

VSA

class claripy.vsa.abstract_location.Segment(offset, size=0)

Bases: object

class claripy.vsa.abstract_location.AbstractLocation(bbl_key, stmt_id, region_id, segment_list=None, region_offset=None, size=None)

Bases: claripy.backend_object.BackendObject

property basicblock_key
property statement_id
property region
property segments
update(region_offset, size)
copy()
merge(other)
class claripy.vsa.bool_result.BoolResult(op=None, args=None)

Bases: claripy.backend_object.BackendObject

value()
identical(other)
union(other)
size()
static is_maybe(o)
static has_true(o)
static has_false(o)
static is_true(o)
static is_false(o)
class claripy.vsa.bool_result.TrueResult(op=None, args=None)

Bases: claripy.vsa.bool_result.BoolResult

cardinality = 1
property value
identical(other)
union(other)
class claripy.vsa.bool_result.FalseResult(op=None, args=None)

Bases: claripy.vsa.bool_result.BoolResult

cardinality = 1
property value
identical(other)
union(other)
class claripy.vsa.bool_result.MaybeResult(op=None, args=None)

Bases: claripy.vsa.bool_result.BoolResult

cardinality = 2
property value
identical(other)
union(other)
claripy.vsa.discrete_strided_interval_set.apply_on_each_si(f)
claripy.vsa.discrete_strided_interval_set.convert_operand_to_si(f)
claripy.vsa.discrete_strided_interval_set.collapse_operand(f)
class claripy.vsa.discrete_strided_interval_set.DiscreteStridedIntervalSet(name=None, bits=0, si_set=None, max_cardinality=None)

Bases: claripy.vsa.strided_interval.StridedInterval

A DiscreteStridedIntervalSet represents one or more discrete StridedInterval instances.

property cardinality

This is an over-approximation of the cardinality of this DSIS.

Returns

property number_of_values
property stride
should_collapse()
collapse()

Collapse into a StridedInterval instance.

Returns

A new StridedInterval instance.

normalize()

Return the collapsed object if should_collapse() is True, otherwise return self.

Returns

A DiscreteStridedIntervalSet object.

copy()
concat(b)

Operation concat

Parameters

b – The other operand to concatenate with.

Returns

The concatenated value.

extract(high_bit, low_bit)

Operation extract

Parameters
  • high_bit – The highest bit to begin extraction.

  • low_bit – The lowest bit to end extraction.

Returns

Extracted bits.

eval(n, signed=False)
Parameters
  • n

  • signed

Returns

union(b)
intersection(b)
reverse()

Operation Reverse

Returns

None

sign_extend(new_length)

Operation SignExt

Parameters

new_length – The length to extend to.

Returns

SignExtended value.

zero_extend(new_length)

Operation ZeroExt

Parameters

new_length – The length to extend to.

Returns

ZeroExtended value.

widen(b)

Widening operator.

Parameters

b – The other operand.

Returns

The widened result.

exception claripy.vsa.errors.ClaripyVSAError

Bases: claripy.errors.ClaripyError

exception claripy.vsa.errors.ClaripyVSAOperationError

Bases: claripy.vsa.errors.ClaripyVSAError

claripy.vsa.strided_interval.reversed_processor(f)
claripy.vsa.strided_interval.normalize_types(f)
class claripy.vsa.strided_interval.WarrenMethods

Bases: object

Methods as suggested in book. Hackers Delight.

static min_or(a, b, c, d, w)

Lower bound of result of ORing 2-intervals.

Parameters
  • a – Lower bound of first interval

  • b – Upper bound of first interval

  • c – Lower bound of second interval

  • d – Upper bound of second interval

  • w – bit width

Returns

Lower bound of ORing 2-intervals

static max_or(a, b, c, d, w)

Upper bound of result of ORing 2-intervals.

Parameters
  • a – Lower bound of first interval

  • b – Upper bound of first interval

  • c – Lower bound of second interval

  • d – Upper bound of second interval

  • w – bit width

Returns

Upper bound of ORing 2-intervals

static min_and(a, b, c, d, w)

Lower bound of result of ANDing 2-intervals.

Parameters
  • a – Lower bound of first interval

  • b – Upper bound of first interval

  • c – Lower bound of second interval

  • d – Upper bound of second interval

  • w – bit width

Returns

Lower bound of ANDing 2-intervals

static max_and(a, b, c, d, w)

Upper bound of result of ANDing 2-intervals.

Parameters
  • a – Lower bound of first interval

  • b – Upper bound of first interval

  • c – Lower bound of second interval

  • d – Upper bound of second interval

  • w – bit width

Returns

Upper bound of ANDing 2-intervals

static min_xor(a, b, c, d, w)

Lower bound of result of XORing 2-intervals.

Parameters
  • a – Lower bound of first interval

  • b – Upper bound of first interval

  • c – Lower bound of second interval

  • d – Upper bound of second interval

  • w – bit width

Returns

Lower bound of XORing 2-intervals

static max_xor(a, b, c, d, w)

Upper bound of result of XORing 2-intervals.

Parameters
  • a – Lower bound of first interval

  • b – Upper bound of first interval

  • c – Lower bound of second interval

  • d – Upper bound of second interval

  • w – bit width

Returns

Upper bound of XORing 2-intervals

class claripy.vsa.strided_interval.StridedInterval(name=None, bits=0, stride=None, lower_bound=None, upper_bound=None, uninitialized=False, bottom=False)

Bases: claripy.backend_object.BackendObject

A Strided Interval is represented in the following form:

<bits> stride[lower_bound, upper_bound]

For more details, please refer to relevant papers like TIE and WYSINWYE.

This implementation is signedness-agostic, please refer to [1] Signedness-Agnostic Program Analysis: Precise Integer Bounds for Low-Level Code by Jorge A. Navas, etc. for more details. Note that this implementation only takes hint from [1]. Such a work has been improved to be more precise (and still sound) when dealing with strided intervals. DO NOT expect to see a 1-to-1 reproduction of [1].

Thanks all corresponding authors for their outstanding works.

copy()
nameless_copy()
normalize()
eval(n, signed=False)

Evaluate this StridedInterval to obtain a list of concrete integers.

Parameters
  • n – Upper bound for the number of concrete integers

  • signed – Treat this StridedInterval as signed or unsigned

Returns

A list of at most n concrete integers

solution(b)

Checks whether an integer is solution of the current strided Interval :param b: integer to check :return: True if b belongs to the current Strided Interval, False otherwhise

identical(o)

Used to make exact comparisons between two StridedIntervals. Usually it is only used in test cases.

Parameters

o – The other StridedInterval to compare with.

Returns

True if they are exactly same, False otherwise.

SLT(o)

Signed less than

Parameters

o – The other operand

Returns

TrueResult(), FalseResult(), or MaybeResult()

SLE(o)

Signed less than or equal to.

Parameters

o – The other operand.

Returns

TrueResult(), FalseResult(), or MaybeResult()

SGT(o)

Signed greater than.

Parameters

o – The other operand

Returns

TrueResult(), FalseResult(), or MaybeResult()

SGE(o)

Signed greater than or equal to.

Parameters

o – The other operand

Returns

TrueResult(), FalseResult(), or MaybeResult()

ULT(o)

Unsigned less than.

Parameters

o – The other operand

Returns

TrueResult(), FalseResult(), or MaybeResult()

ULE(o)

Unsigned less than or equal to.

Parameters

o – The other operand

Returns

TrueResult(), FalseResult(), or MaybeResult()

UGT(o)

Signed greater than.

Parameters

o – The other operand

Returns

TrueResult(), FalseResult(), or MaybeResult()

UGE(o)

Unsigned greater than or equal to.

Parameters

o – The other operand

Returns

TrueResult(), FalseResult(), or MaybeResult()

eq(o)

Equal

Parameters

o – The ohter operand

Returns

TrueResult(), FalseResult(), or MaybeResult()

LShR(shift_amount)

Logical shift right. :param StridedInterval shift_amount: The amount of shifting :return: The shifted StridedInterval object :rtype: StridedInterval

property name
property reversed
property size
property cardinality
property complement

Return the complement of the interval Refer section 3.1 augmented for managing strides

Returns

property lower_bound
property upper_bound
property bits
property stride
property max
property min
property unique
property is_empty

The same as is_bottom :return: True/False

property is_top

If this is a TOP value.

Returns

True if this is a TOP

property is_bottom

Whether this StridedInterval is a BOTTOM, in other words, describes an empty set of integers.

Returns

True/False

property is_integer

If this is an integer, i.e. self.lower_bound == self.upper_bound.

Returns

True if this is an integer, False otherwise

property is_interval
property n_values
static lcm(a, b)

Get the least common multiple.

Parameters
  • a – The first operand (integer)

  • b – The second operand (integer)

Returns

Their LCM

static gcd(a, b)

Get the greatest common divisor.

Parameters
  • a – The first operand (integer)

  • b – The second operand (integer)

Returns

Their GCD

static highbit(k)
static min_bits(val, max_bits=None)
static max_int(k)
static min_int(k)
static signed_max_int(k)
static signed_min_int(k)
static upper(bits, i, stride)
Returns

static lower(bits, i, stride)
Returns

static top(bits, name=None, uninitialized=False)

Get a TOP StridedInterval.

Returns

static empty(bits)
neg(*args, **kwargs)
add(b)

Binary operation: add

Parameters

b – The other operand

Returns

self + b

sub(b)

Binary operation: sub

Parameters

b – The other operand

Returns

self - b

mul(o)

Binary operation: multiplication

Parameters

o – The other operand

Returns

self * o

sdiv(o)

Binary operation: signed division

Parameters

o – The divisor

Returns

(self / o) in signed arithmetic

udiv(o)

Binary operation: unsigned division

Parameters

o – The divisor

Returns

(self / o) in unsigned arithmetic

bitwise_not(*args, **kwargs)
bitwise_or(t)

Binary operation: logical or

Parameters

b – The other operand

Returns

self | b

bitwise_and(t)

Binary operation: logical and

Parameters

b – The other operand

Returns

bitwise_xor(t)

Operation xor

Parameters

t – The other operand.

rshift_logical(*args, **kwargs)
rshift_arithmetic(*args, **kwargs)
lshift(*args, **kwargs)
cast_low(*args, **kwargs)
concat(b)
extract(*args, **kwargs)
agnostic_extend(*args, **kwargs)
zero_extend(*args, **kwargs)
sign_extend(*args, **kwargs)
union(b)

The union operation. It might return a DiscreteStridedIntervalSet to allow for better precision in analysis.

Parameters

b – Operand

Returns

A new DiscreteStridedIntervalSet, or a new StridedInterval.

static least_upper_bound(*intervals_to_join)

Pseudo least upper bound. Join the given set of intervals into a big interval. The resulting strided interval is the one which in all the possible joins of the presented SI, presented the least number of values.

The number of joins to compute is linear with the number of intervals to join.

Draft of proof: Considering three generic SI (a,b, and c) ordered from their lower bounds, such that a.lower_bund <= b.lower_bound <= c.lower_bound, where <= is the lexicographic less or equal. The only joins which have sense to compute are: * a U b U c * b U c U a * c U a U b

All the other combinations fall in either one of these cases. For example: b U a U c does not make make sense to be calculated. In fact, if one draws this union, the result is exactly either (b U c U a) or (a U b U c) or (c U a U b). :param intervals_to_join: Intervals to join :return: Interval that contains all intervals

static pseudo_join(s, b, smart_join=True)

It two intervals in a way that the resulting SI is the one that has the least SI cardinality (i.e., which represents the least number of elements) possible if the smart_join flag is enabled, otherwise it just joins the SI according the order they are passed to the function.

The pseudo-join operation is not associative in wrapping intervals (please refer to section 3.1 paper ‘Signedness-Agnostic Program Analysis: Precise Integer Bounds for Low-Level Code’), Therefore the join of three WI may give us different results according on the order we join them. All of the results will be sound, though.

Please use the function least_upper_bound as a stub.

Parameters
  • s – The first SI

  • b – The other SI.

  • smart_join – Enable the smart join behavior. If this flag is set, this function joins the two SI in a way that the resulting Si has least number of elements (more precise). If it is unset, this function will join the two SI according on the order they are passed to the function.

Returns

A new StridedInterval

static extended_euclid(a, b)

It calculates the GCD of a and b, and two values x and y such that: a*x + b*y = GCD(a,b). This code has been taken from the project sympy.

Parameters
  • a – first integer

  • b – second integer

Returns

x,y and the GCD of a and b

static sign(a)
static igcd(a, b)
Parameters
  • a – First integer

  • b – Second integer

Returns

the integer GCD between a and b

static diop_natural_solution_linear(c, a, b)

It finds the fist natural solution of the diophantine equation a*x + b*y = c. Some lines of this code are taken from the project sympy.

Parameters
  • c – constant

  • a – quotient of x

  • b – quotient of y

Returns

the first natural solution of the diophatine equation

intersection(b)
widen(b)
reverse()

This is a delayed reversing function. All it really does is to invert the _reversed property of this StridedInterval object.

Returns

None

claripy.vsa.strided_interval.CreateStridedInterval(name=None, bits=0, stride=None, lower_bound=None, upper_bound=None, uninitialized=False, to_conv=None, discrete_set=False, discrete_set_max_cardinality=None)
Parameters
  • name

  • bits

  • stride

  • lower_bound

  • upper_bound

  • to_conv

  • discrete_set (bool) –

  • discrete_set_max_cardinality (int) –

Returns

claripy.vsa.valueset.normalize_types_two_args(f)
claripy.vsa.valueset.normalize_types_one_arg(f)
class claripy.vsa.valueset.RegionAnnotation(region_id, region_base_addr, offset)

Bases: claripy.annotation.Annotation

Use RegionAnnotation to annotate ASTs. Normally, an AST annotated by RegionAnnotations is treated as a ValueSet.

Note that Annotation objects are immutable. Do not change properties of an Annotation object without creating a new one.

property eliminatable

A Region annotation is not eliminatable in simplifications.

Returns

False

Return type

bool

property relocatable

A Region annotation is not relocatable in simplifications.

Returns

False

Return type

bool

relocate(src, dst)

Override Annotation.relocate().

Parameters
  • src – The old AST

  • dst – The new AST, as the result of a simplification

Returns

The new annotation that should be applied on the new AST

class claripy.vsa.valueset.ValueSet(name=None, region=None, region_base_addr=None, bits=None, val=None)

Bases: claripy.backend_object.BackendObject

ValueSet is a mapping between memory regions and corresponding offsets.

Constructor.

Parameters
  • name (str) – Name of this ValueSet object. Only for debugging purposes.

  • region (str) – Region ID.

  • region_base_addr (int) – Base address of the region.

  • bits (int) – Size of the ValueSet.

  • val – an initial offset

property name
property bits
property regions
property reversed
property unique
property cardinality
property is_empty
property valueset
static empty(bits)
items()
size()
copy()

Make a copy of self and return.

Returns

A new ValueSet object.

Return type

ValueSet

get_si(region)
stridedinterval()
apply_annotation(annotation)

Apply a new annotation onto self, and return a new ValueSet object.

Parameters

annotation (RegionAnnotation) – The annotation to apply.

Returns

A new ValueSet object

Return type

ValueSet

eval(n, signed=False)
property min

The minimum integer value of a value-set. It is only defined when there is exactly one region.

Returns

A integer that represents the minimum integer value of this value-set.

Return type

int

property max

The maximum integer value of a value-set. It is only defined when there is exactly one region.

Returns

A integer that represents the maximum integer value of this value-set.

Return type

int

reverse()
extract(high_bit, low_bit)

Operation extract

  • A cheap hack is implemented: a copy of self is returned if (high_bit - low_bit + 1 == self.bits), which is a

    ValueSet instance. Otherwise a StridedInterval is returned.

Parameters
  • high_bit

  • low_bit

Returns

A ValueSet or a StridedInterval

concat(b)
union(b)
widen(b)
intersection(b)
identical(o)

Used to make exact comparisons between two ValueSets.

Parameters

o – The other ValueSet to compare with.

Returns

True if they are exactly same, False otherwise.

Misc. Things

claripy.BV(name, size, explicit_name=None)
claripy.downsize()

Clear all temporary data associated with any backend

claripy.reset()

Attempt to refresh any caching state associated with the module

class claripy.balancer.Balancer(helper, c, validation_frontend=None)

Bases: object

The Balancer is an equation redistributor. The idea is to take an AST and rebalance it to, for example, isolate unknown terms on one side of an inequality.

property compat_ret
property replacements
comparison_info = {'SGE': (False, True, False), 'SGT': (False, False, False), 'SLE': (True, True, False), 'SLT': (True, False, False), 'UGE': (False, True, True), 'UGT': (False, False, True), 'ULE': (True, True, True), 'ULT': (True, False, True), '__ge__': (False, True, True), '__gt__': (False, False, True), '__le__': (True, True, True), '__lt__': (True, False, True)}
claripy.balancer.is_true(a)
claripy.balancer.is_false(a)
claripy.bv.compare_bits(f)
claripy.bv.compare_bits_0_length(f)
claripy.bv.normalize_types(f)
class claripy.bv.BVV(value, bits)

Bases: claripy.backend_object.BackendObject

bits
mod
property value
property signed
size()
claripy.bv.BitVecVal(value, bits)
claripy.bv.ZeroExt(num, o)
claripy.bv.SignExt(num, o)
claripy.bv.Extract(f, t, o)
claripy.bv.Concat(*args)
claripy.bv.RotateRight(self, bits)
claripy.bv.RotateLeft(self, bits)
claripy.bv.Reverse(a)
claripy.bv.ULT(self, o)
claripy.bv.UGT(self, o)
claripy.bv.ULE(self, o)
claripy.bv.UGE(self, o)
claripy.bv.SLT(self, o)
claripy.bv.SGT(self, o)
claripy.bv.SLE(self, o)
claripy.bv.SGE(self, o)
claripy.bv.SMod(self, o)
claripy.bv.SDiv(self, o)
claripy.bv.BoolV(b)
claripy.bv.And(*args)
claripy.bv.Or(*args)
claripy.bv.Not(b)
claripy.bv.normalizer(*args)
claripy.bv.If(c, t, f)
claripy.bv.LShR(a, b)
exception claripy.errors.ClaripyError

Bases: Exception

exception claripy.errors.UnsatError

Bases: claripy.errors.ClaripyError

exception claripy.errors.ClaripyFrontendError

Bases: claripy.errors.ClaripyError

exception claripy.errors.ClaripySerializationError

Bases: claripy.errors.ClaripyError

exception claripy.errors.BackendError

Bases: claripy.errors.ClaripyError

exception claripy.errors.BackendUnsupportedError

Bases: claripy.errors.BackendError

exception claripy.errors.ClaripyZ3Error

Bases: claripy.errors.ClaripyError

exception claripy.errors.ClaripyBackendVSAError

Bases: claripy.errors.BackendError

exception claripy.errors.MissingSolverError

Bases: claripy.errors.ClaripyError

exception claripy.errors.ClaripyASTError

Bases: claripy.errors.ClaripyError

exception claripy.errors.ClaripyBalancerError

Bases: claripy.errors.ClaripyASTError

exception claripy.errors.ClaripyBalancerUnsatError

Bases: claripy.errors.ClaripyBalancerError

exception claripy.errors.ClaripyTypeError

Bases: claripy.errors.ClaripyASTError

exception claripy.errors.ClaripyValueError

Bases: claripy.errors.ClaripyASTError

exception claripy.errors.ClaripySizeError

Bases: claripy.errors.ClaripyASTError

exception claripy.errors.ClaripyOperationError

Bases: claripy.errors.ClaripyASTError

exception claripy.errors.ClaripyReplacementError

Bases: claripy.errors.ClaripyASTError

exception claripy.errors.ClaripyRecursionError

Bases: claripy.errors.ClaripyOperationError

exception claripy.errors.ClaripyZeroDivisionError

Bases: claripy.errors.ClaripyOperationError, ZeroDivisionError

claripy.fp.compare_sorts(f)
claripy.fp.normalize_types(f)
class claripy.fp.RM(value)

Bases: enum.Enum

An enumeration.

RM_NearestTiesEven = 'RM_RNE'
RM_NearestTiesAwayFromZero = 'RM_RNA'
RM_TowardsZero = 'RM_RTZ'
RM_TowardsPositiveInf = 'RM_RTP'
RM_TowardsNegativeInf = 'RM_RTN'
static default()
pydecimal_equivalent_rounding_mode()
class claripy.fp.FSort(name, exp, mantissa)

Bases: object

property length
static from_size(n)
static from_params(exp, mantissa)
class claripy.fp.FPV(value, sort)

Bases: claripy.backend_object.BackendObject

value
sort
claripy.fp.fpToFP(a1, a2, a3=None)

Returns a FP AST and has three signatures:

fpToFP(ubvv, sort)

Returns a FP AST whose value is the same as the unsigned BVV a1 and whose sort is a2.

fpToFP(rm, fpv, sort)

Returns a FP AST whose value is the same as the floating point a2 and whose sort is a3.

fpToTP(rm, sbvv, sort)

Returns a FP AST whose value is the same as the signed BVV a2 and whose sort is a3.

claripy.fp.fpToFPUnsigned(_rm, thing, sort)

Returns a FP AST whose value is the same as the unsigned BVV thing and whose sort is sort.

claripy.fp.fpToIEEEBV(fpv)

Interprets the bit-pattern of the IEEE754 floating point number fpv as a bitvector.

Returns

A BV AST whose bit-pattern is the same as fpv

claripy.fp.fpFP(sgn, exp, mantissa)

Concatenates the bitvectors sgn, exp and mantissa and returns the corresponding IEEE754 floating point number.

Returns

A FP AST whose bit-pattern is the same as the concatenated bitvector

claripy.fp.fpToSBV(rm, fp, size)
claripy.fp.fpToUBV(rm, fp, size)
claripy.fp.fpEQ(a, b)

Checks if floating point a is equal to floating point b.

claripy.fp.fpNE(a, b)

Checks if floating point a is not equal to floating point b.

claripy.fp.fpGT(a, b)

Checks if floating point a is greater than floating point b.

claripy.fp.fpGEQ(a, b)

Checks if floating point a is greater than or equal to floating point b.

claripy.fp.fpLT(a, b)

Checks if floating point a is less than floating point b.

claripy.fp.fpLEQ(a, b)

Checks if floating point a is less than or equal to floating point b.

claripy.fp.fpAbs(x)

Returns the absolute value of the floating point x. So:

a = FPV(-3.2, FSORT_DOUBLE) b = fpAbs(a) b is FPV(3.2, FSORT_DOUBLE)

claripy.fp.fpNeg(x)

Returns the additive inverse of the floating point x. So:

a = FPV(3.2, FSORT_DOUBLE) b = fpAbs(a) b is FPV(-3.2, FSORT_DOUBLE)

claripy.fp.fpSub(_rm, a, b)

Returns the subtraction of the floating point a by the floating point b.

claripy.fp.fpAdd(_rm, a, b)

Returns the addition of two floating point numbers, a and b.

claripy.fp.fpMul(_rm, a, b)

Returns the multiplication of two floating point numbers, a and b.

claripy.fp.fpDiv(_rm, a, b)

Returns the division of the floating point a by the floating point b.

claripy.fp.fpIsNaN(x)

Checks whether the argument is a floating point NaN.

claripy.fp.fpIsInf(x)

Checks whether the argument is a floating point infinity.

claripy.operations.op(name, arg_types, return_type, extra_check=None, calc_length=None, do_coerce=True, bound=True)
claripy.operations.reversed_op(op_func)
claripy.operations.preprocess_union(*args, **kwargs)
claripy.operations.length_same_check(*args)
claripy.operations.basic_length_calc(*args)
claripy.operations.extract_check(high, low, bv)
claripy.operations.concat_length_calc(*args)
claripy.operations.extract_length_calc(high, low, _)
claripy.operations.str_basic_length_calc(str_1)
claripy.operations.str_extract_check(start_idx, count, str_val)
claripy.operations.str_extract_length_calc(start_idx, count, str_val)
claripy.operations.int_to_str_length_calc(int_val)
claripy.operations.str_replace_check(*args)
claripy.operations.substr_length_calc(start_idx, count, strval)
claripy.operations.ext_length_calc(ext, orig)
claripy.operations.str_concat_length_calc(*args)
claripy.operations.str_replace_length_calc(*args)
claripy.operations.strlen_bv_size_calc(s, bitlength)
claripy.operations.strindexof_bv_size_calc(s1, s2, start_idx, bitlength)
claripy.operations.strtoint_bv_size_calc(s, bitlength)
class claripy.simplifications.SimplificationManager

Bases: object

simplify(op, args)
static if_simplifier(cond, if_true, if_false)
static concat_simplifier(*args)
static rshift_simplifier(val, shift)
static lshr_simplifier(val, shift)
static lshift_simplifier(val, shift)
static eq_simplifier(a, b)
static ne_simplifier(a, b)
static bv_reverse_simplifier(body)
static boolean_and_simplifier(*args)
static boolean_or_simplifier(*args)
static bitwise_add_simplifier(*args)
static bitwise_mul_simplifier(*args)
static bitwise_sub_simplifier(a, b)
static bitwise_xor_simplifier_minmax(a, b)
static bitwise_xor_simplifier(a, b, *args)
static bitwise_or_simplifier(a, b, *args)
static bitwise_and_simplifier(a, b, *args)
static boolean_not_simplifier(body)
static zeroext_simplifier(n, e)
static signext_simplifier(n, e)
static extract_simplifier(high, low, val)
static fptobv_simplifier(the_fp)
static fptofp_simplifier(*args)
static rotate_shift_mask_simplifier(a, b)
Handles the following case:
((A << a) | (A >> (_N - a))) & mask, where

A being a BVS, a being a integer that is less than _N, _N is either 32 or 64, and mask can be evaluated to 0xffffffff (64-bit) or 0xffff (32-bit) after reversing the rotate-shift operation.

It will be simplified to:

(A & (mask >>> a)) <<< a

static str_extract_simplifier(start_idx, count, val)
static str_reverse_simplifier(arg)
static and_mask_comparing_against_constant_simplifier(op, a, b)

This simplifier handles the following case:

A & mask == b, and A & mask != b

If the high bits of A are 0, & mask can be eliminated.

static zeroext_extract_comparing_against_constant_simplifier(op, a, b)

This simplifier handles the following cases:

Extract(hi, 0, Concat(0, A)) op b, and Extract(hi, 0, ZeroExt(n, A)) op b

Extract can be eliminated if the high bits of Concat(0, A) or ZeroExt(n, A) are all zeros.

static zeroext_comparing_against_simplifier(op, a, b)

This simplifier handles the following cases:

ZeroExt(n, A) == b, and ZeroExt(n, A) != b

If the high bits of b are all zeros (in case of __eq__) or have at least one ones (in case of __ne__), ZeroExt can be eliminated.

claripy.ops.AbstractLocation(*args, **kwargs)
claripy.smtlib_utils.make_pysmt_const_from_type(val, type)
class claripy.smtlib_utils.SMTParser(tokens)

Bases: object

expect(*allowed)
expect_assignment_tuple()
consume_assignment_list()
class claripy.strings.StringV(value)

Bases: claripy.backend_object.BackendObject

claripy.strings.StrConcat(*args)

Concatenate a sequence of strings.

Parameters

args – list of string that has to be concatenated

Returns

the concatenated string

claripy.strings.StrSubstr(start_idx, count, initial_string)

Return the substring of length count starting at start_idx.

Parameters
  • start_idx – starting index of the substring

  • count – length of the substring in bytes

  • initial_string – original string

Returns

the substring

claripy.strings.StrExtract(high, low, str_val)
claripy.strings.StrReplace(initial_string, pattern_to_be_replaced, replacement_pattern)

Return string where the first occurrence of pattern_to_be_replaced is replaced with replacement_pattern.

Parameters
  • initial_string – string in which the pattern needs to be replaced

  • pattern_to_be_replaced – substring that has to be replaced inside initial_string

  • replacement_pattern – pattern that has to be inserted in initial_string to replace pattern_to_be_replaced

Returns

string with replacement

claripy.strings.StrLen(input_string, bitlength)

Return length of the input_string in bytes.

Parameters
  • input_string – the string we want to calculate the length

  • bitlength – length of the bitvector representing the length of the string

Returns

bitvector holding the size of the string in bytes

claripy.strings.StrContains(input_string, substring)

Check if substring is contained in input_string.

Parameters
  • input_string – the string we want to check

  • substring – the string we want to check if it’s contained inside the input_string

Returns

True if substring is contained in input_string else False

claripy.strings.StrPrefixOf(prefix, input_string)

Check if input_string starts with prefix.

Parameters
  • prefix – prefix we want to check

  • input_string – the string we want to check

Returns

True if the input_string starts with prefix else False

claripy.strings.StrSuffixOf(suffix, input_string)

Check if input_string ends with suffix.

Parameters
  • suffix – suffix we want to check

  • input_string – the string we want to check

:return : True if the input_string ends with suffix else False

claripy.strings.StrIndexOf(input_string, substring, startIndex, bitlength)

Return the index of the first occurrence of substring at or after the startIndex, or -1 if it is not found.

Parameters
  • input_string – the string we want to check

  • substring – the substring we want to find the index

  • startIndex – the index to start searching at

  • bitlength – length of the bitvector representing the index of the substring

Return BV

index of the substring or -1 in bitvector

claripy.strings.StrToInt(input_string, bitlength)

Return the integer representation of input_string.

Parameters
  • input_string – the string we want to transform in an integer

  • bitlength – length of the bitvector representing the index of the substring

Return BV

bitvector of the integer resulting from the string or -1 in bitvector if the string cannot be transformed into an integer

claripy.strings.StrIsDigit(input_string)

Determine whether input_string is entirely numeric.

Parameters

input_string – the string we want to check

Returns

True if the string is entirely numeric otherwise False

claripy.strings.IntToStr(input_bvv)

Return the string representation of input_bvv.

Parameters

input_bvv – the integer to be expressed as a string

Returns

the string representation of the integer

claripy.debug.set_debug(enabled)

Enable or disable the debug mode. In debug mode, a bunch of extra checks in claripy will be executed. You’ll want to disable debug mode if you are running performance critical code.