angr.knowledge_plugins.key_definitions

class angr.knowledge_plugins.key_definitions.Definition

Bases: Generic

An atom definition.

Variables:

• atom – The atom being defined.

• codeloc – Where this definition is created in the original binary code.

• dummy – Tell whether the definition should be considered dummy or not. During simplification by AILment, definitions marked as dummy will not be removed.

• tags – A set of tags containing information about the definition gathered during analyses.

__init__(atom, codeloc, dummy=False, tags=None)

Parameters:

• atom (A)

• codeloc (CodeLoc)

• dummy (bool)

• tags (set[Tag] | None)

atom

codeloc

dummy

tags

property offset: int

property size: int

matches(**kwargs)

Return whether this definition has certain characteristics.

Return type:

bool

class angr.knowledge_plugins.key_definitions.DerefSize

Bases: Enum

An enum for specialized kinds of dereferences

NULL_TERMINATE - Dereference until the first byte which could be a literal null. Return a value including the

terminator.

NULL_TERMINATE = 1

class angr.knowledge_plugins.key_definitions.KeyDefinitionManager

Bases: KnowledgeBasePlugin

KeyDefinitionManager manages and caches reaching definition models for each function.

For each function, by default we cache the entire reaching definitions model with observed results at the following locations: - Before each call instruction: (‘insn’, address of the call instruction, OP_BEFORE) - After returning from each call: (‘node’, address of the block that ends with a call, OP_AFTER)

__init__(kb)

Parameters:

kb (KnowledgeBase)

has_model(func_addr)

Parameters:

func_addr (int)

get_model(func_addr)

Parameters:

func_addr (int)

copy()

Return type:

KeyDefinitionManager

class angr.knowledge_plugins.key_definitions.LiveDefinitions

Bases: object

A LiveDefinitions instance contains definitions and uses for register, stack, memory, and temporary variables, uncovered during the analysis.

INITIAL_SP_16BIT = 32512

INITIAL_SP_32BIT = 2147418112

INITIAL_SP_64BIT = 140737488289792

__init__(arch, track_tmps=False, canonical_size=8, registers=None, stack=None, memory=None, heap=None, tmps=None, others=None, register_uses=None, stack_uses=None, heap_uses=None, memory_uses=None, tmp_uses=None, other_uses=None, element_limit=5, merge_into_tops=True)

Parameters:

• arch (Arch)

• track_tmps (bool)

• merge_into_tops (bool)

project: Project | None

arch

track_tmps

registers: MultiValuedMemory

stack: MultiValuedMemory

memory: MultiValuedMemory

heap: MultiValuedMemory

tmps: dict[int, set[Definition]]

others: dict[Atom, MultiValues]

register_uses

stack_uses

heap_uses

memory_uses

tmp_uses: dict[int, set[CodeLocation]]

other_uses

uses_by_codeloc: dict[CodeLocation, set[Definition]]

copy(discard_tmpdefs=False)

Return type:

LiveDefinitions

reset_uses()

static top(bits)

Get a TOP value.

Parameters:

bits (int) – Width of the TOP value (in bits).

Returns:

The TOP value.

static is_top(expr)

Check if the given expression is a TOP value.

Parameters:

expr – The given expression.

Return type:

bool

Returns:

True if the expression is TOP, False otherwise.

stack_address(offset)

Return type:

BV

Parameters:

offset (int)

static is_stack_address(addr)

Return type:

bool

Parameters:

addr (Base)

static get_stack_offset(addr, had_stack_base=False)

Return type:

int | None

Parameters:

addr (Base)

static annotate_with_def(symvar, definition)

Parameters:

• symvar (TypeVar(MVType, bound= BV | FP))

• definition (Definition)

Return type:

TypeVar(MVType, bound= BV | FP)

Returns:

static extract_defs(symvar)

Return type:

Generator[Definition]

Parameters:

symvar (Base)

static extract_defs_from_annotations(annos)

Return type:

set[Definition]

Parameters:

annos (Iterable[Annotation])

static extract_defs_from_mv(mv)

Return type:

Generator[Definition]

Parameters:

mv (MultiValues)

get_sp()

Return the concrete value contained by the stack pointer.

Return type:

int

get_sp_offset()

Return the offset of the stack pointer.

Return type:

int | None

get_stack_address(offset)

Return type:

int | None

Parameters:

offset (Base)

stack_offset_to_stack_addr(offset)

Return type:

int

merge(*others)

Return type:

tuple[LiveDefinitions, bool]

Parameters:

others (LiveDefinitions)

compare(other)

Return type:

bool

Parameters:

other (LiveDefinitions)

kill_definitions(atom)

Overwrite existing definitions w.r.t ‘atom’ with a dummy definition instance. A dummy definition will not be removed during simplification.

Parameters:

atom (Atom)

Return type:

None

Returns:

None

kill_and_add_definition(atom, code_loc, data, dummy=False, tags=None, endness=None, annotated=False)

Return type:

MultiValues | None

Parameters:

• atom (Atom)

• code_loc (CodeLocation)

• data (MultiValues)

• tags (set[Tag] | None)

add_use(atom, code_loc, expr=None)

Return type:

None

Parameters:

• atom (Atom)

• code_loc (CodeLocation)

• expr (Any | None)

add_use_by_def(definition, code_loc, expr=None)

Return type:

None

Parameters:

• definition (Definition)

• code_loc (CodeLocation)

• expr (Any)

get_definitions(thing)

get_tmp_definitions(tmp_idx)

Return type:

set[Definition]

Parameters:

tmp_idx (int)

get_register_definitions(reg_offset, size)

Return type:

set[Definition]

Parameters:

• reg_offset (int)

• size (int)

get_stack_values(stack_offset, size, endness)

Return type:

MultiValues | None

Parameters:

• stack_offset (int)

• size (int)

• endness (str)

get_stack_definitions(stack_offset, size)

Return type:

set[Definition]

Parameters:

• stack_offset (int)

• size (int)

get_heap_definitions(heap_addr, size)

Return type:

set[Definition]

Parameters:

• heap_addr (int)

• size (int)

get_memory_definitions(addr, size)

Return type:

set[Definition]

Parameters:

• addr (int)

• size (int)

get_values(spec, endness=None)

get_one_value(spec, strip_annotations=False)

get_concrete_value(spec, cast_to=<class 'int'>)

Overloads:

• self, spec (A | Definition[A] | Iterable[A] | Iterable[Definition[A]]), cast_to (type[int]) → int | None

• self, spec (A | Definition[A] | Iterable[A] | Iterable[Definition[A]]), cast_to (type[bytes]) → bytes | None

add_register_use(reg_offset, size, code_loc, expr=None)

Return type:

None

Parameters:

• reg_offset (int)

• size (int)

• code_loc (CodeLocation)

• expr (Any | None)

add_register_use_by_def(def_, code_loc, expr=None)

Return type:

None

Parameters:

• def_ (Definition)

• code_loc (CodeLocation)

• expr (Any | None)

add_stack_use(atom, code_loc, expr=None)

Return type:

None

Parameters:

• atom (MemoryLocation)

• code_loc (CodeLocation)

• expr (Any | None)

add_stack_use_by_def(def_, code_loc, expr=None)

Return type:

None

Parameters:

• def_ (Definition)

• code_loc (CodeLocation)

• expr (Any | None)

add_heap_use(atom, code_loc, expr=None)

Return type:

None

Parameters:

• atom (MemoryLocation)

• code_loc (CodeLocation)

• expr (Any | None)

add_heap_use_by_def(def_, code_loc, expr=None)

Return type:

None

Parameters:

• def_ (Definition)

• code_loc (CodeLocation)

• expr (Any | None)

add_memory_use(atom, code_loc, expr=None)

Return type:

None

Parameters:

• atom (MemoryLocation)

• code_loc (CodeLocation)

• expr (Any | None)

add_memory_use_by_def(def_, code_loc, expr=None)

Return type:

None

Parameters:

• def_ (Definition)

• code_loc (CodeLocation)

• expr (Any | None)

add_tmp_use(atom, code_loc)

Return type:

None

Parameters:

• atom (Tmp)

• code_loc (CodeLocation)

add_tmp_use_by_def(def_, code_loc)

Return type:

None

Parameters:

• def_ (Definition)

• code_loc (CodeLocation)

deref(pointer, size, endness=Endness.BE)

Overloads:

• self, pointer (MultiValues[claripy.ast.BV] | Atom | Definition[Atom] | Iterable[Atom] | Iterable[Definition[Atom]]), size (int | DerefSize), endness (archinfo.Endness) → set[MemoryLocation]

• self, pointer (int | claripy.ast.BV | HeapAddress | SpOffset), size (int | DerefSize), endness (archinfo.Endness) → MemoryLocation | None

static is_heap_address(addr)

Return type:

bool

Parameters:

addr (Base)

static get_heap_offset(addr)

Return type:

int | None

Parameters:

addr (Base)

heap_address(offset)

Return type:

BV

Parameters:

offset (int | HeapAddress)

class angr.knowledge_plugins.key_definitions.ReachingDefinitionsModel

Bases: object

Models the definitions, uses, and memory of a ReachingDefinitionState object

__init__(func_addr=None, track_liveness=True)

Parameters:

• func_addr (int | None)

• track_liveness (bool)

add_def(d)

Return type:

None

Parameters:

d (Definition)

kill_def(d)

Return type:

None

Parameters:

d (Definition)

at_new_stmt(codeloc)

Return type:

None

Parameters:

codeloc (CodeLocation)

at_new_block(code_loc, pred_codelocs)

Return type:

None

Parameters:

• code_loc (CodeLocation)

• pred_codelocs (list[CodeLocation])

make_liveness_snapshot()

Return type:

None

find_defs_at(code_loc, op=ObservationPointType.OP_BEFORE)

Return type:

set[Definition]

Parameters:

• code_loc (CodeLocation)

• op (int)

get_defs(atom, code_loc, op)

Return type:

set[Definition]

Parameters:

• atom (Atom)

• code_loc (CodeLocation)

• op (int)

copy()

Return type:

ReachingDefinitionsModel

merge(model)

Parameters:

model (ReachingDefinitionsModel)

get_observation_by_insn(ins_addr, kind)

Return type:

LiveDefinitions | None

Parameters:

• ins_addr (int | CodeLocation)

• kind (ObservationPointType)

get_observation_by_node(node_addr, kind, node_idx=None)

Return type:

LiveDefinitions | None

Parameters:

• node_addr (int | CodeLocation)

• kind (ObservationPointType)

• node_idx (int | None)

get_observation_by_stmt(arg1, arg2, arg3=None, *, block_idx=None)

Overloads:

• self, codeloc (CodeLocation), kind (ObservationPointType) → LiveDefinitions | None

• self, node_addr (int), stmt_idx (int), kind (ObservationPointType), block_idx (int | None)

get_observation_by_exit(node_addr, stmt_idx, src_node_idx=None)

Return type:

LiveDefinitions | None

Parameters:

• node_addr (int)

• stmt_idx (int)

• src_node_idx (int | None)

class angr.knowledge_plugins.key_definitions.Uses

Bases: object

Describes uses (including the use location and the use expression) for definitions.

__init__(uses_by_definition=None, uses_by_location=None)

Parameters:

• uses_by_definition (DefaultChainMapCOW | None)

• uses_by_location (DefaultChainMapCOW | None)

add_use(definition, codeloc, expr=None)

Add a use for a given definition.

Parameters:

• definition (Definition) – The definition that is used.

• codeloc (CodeLocation) – The code location where the use occurs.

• expr (Any | None) – The expression that uses the specified definition at this location.

get_uses(definition)

Retrieve the uses of a given definition.

Parameters:

definition (Definition) – The definition for which we get the uses.

Return type:

set[CodeLocation]

get_uses_with_expr(definition)

Retrieve the uses and the corresponding expressions of a given definition.

Parameters:

definition (Definition) – The definition for which we get the uses and the corresponding expressions.

Return type:

set[tuple[CodeLocation, Any | None]]

remove_use(definition, codeloc, expr=None)

Remove one use of a given definition.

Parameters:

• definition (Definition) – The definition of which to remove the uses.

• codeloc (CodeLocation) – The code location where the use is.

• expr (Any | None) – The expression that uses the definition at the given location.

Return type:

None

Returns:

None

remove_uses(definition)

Remove all uses of a given definition.

Parameters:

definition (Definition) – The definition of which to remove the uses.

Returns:

None

get_uses_by_location(codeloc, exprs=False)

Retrieve all definitions that are used at a given location.

Parameters:

• codeloc (CodeLocation) – The code location.

• exprs (bool)

Return type:

set[Definition] | set[tuple[Definition, Any | None]]

Returns:

A set of definitions that are used at the given location.

get_uses_by_insaddr(ins_addr, exprs=False)

Retrieve all definitions that are used at a given location specified by the instruction address.

Parameters:

• ins_addr (int) – The instruction address.

• exprs (bool)

Return type:

set[Definition] | set[tuple[Definition, Any | None]]

Returns:

A set of definitions that are used at the given location.

copy()

Copy the instance.

Return type:

Uses

Returns:

Return a new <Uses> instance containing the same data.

merge(other)

Merge an instance of <Uses> into the current instance.

Parameters:

other (Uses) – The other <Uses> from which the data will be added to the current instance.

Return type:

bool

Returns:

True if any merge occurred, False otherwise

Submodules

atoms
constants
definition
environment
heap_address
key_definition_manager
live_definitions
liveness
rd_model
tag	Classes to structure the different types of <Tag>s that can be attached to <Definition>s.
undefined
unknown_size
uses