angr.engines

class angr.engines.HeavyResilienceMixin

Bases: VEXResilienceMixin, ClaripyDataMixin

class angr.engines.HeavyVEXMixin

Bases: SuccessorsEngine, ClaripyDataMixin, SimStateStorageMixin, VEXMixin, VEXLifter

Execution engine based on VEX, Valgrind’s IR.

Responds to the following parameters to the step stack:

  • irsb: The PyVEX IRSB object to use for execution. If not provided one will be lifted.

  • skip_stmts: The number of statements to skip in processing

  • last_stmt: Do not execute any statements after this statement

  • whitelist: Only execute statements in this set

  • thumb: Whether the block should be force to be lifted in ARM’s THUMB mode.

  • extra_stop_points:

    An extra set of points at which to break basic blocks

  • opt_level: The VEX optimization level to use.

  • insn_bytes: A string of bytes to use for the block instead of the project.

  • size: The maximum size of the block, in bytes.

  • num_inst: The maximum number of instructions.

  • traceflags: traceflags to be passed to VEX. (default: 0)

class angr.engines.HooksMixin

Bases: SuccessorsEngine, ProcedureMixin

A SimEngine mixin which adds a SimSuccessors handler which will look into the project’s hooks and run the hook at the current address.

Will respond to the following parameters provided to the step stack:

  • procedure: A SimProcedure instance to force-run instead of consulting the current hooks

  • ret_to: An address to force-return-to at the end of the procedure

class angr.engines.ProcedureEngine

Bases: ProcedureMixin, SuccessorsEngine

A SimEngine that you may use if you only care about processing SimProcedures. Requires the procedure kwarg to be passed to process.

class angr.engines.ProcedureMixin

Bases: object

A mixin for SimEngine which adds the process_procedure method for calling a SimProcedure and adding its results to a SimSuccessors.

process_procedure(state, successors, procedure, ret_to=None, arguments=None, **kwargs)
class angr.engines.SimEngine

Bases: Generic

A SimEngine is a type which understands how to perform execution on a state.

state: StateType
__init__(project)
Parameters:

project (Project)

class angr.engines.SimEngineFailure

Bases: SuccessorsEngine, ProcedureMixin

class angr.engines.SimEngineSyscall

Bases: SuccessorsEngine, ProcedureMixin

A SimEngine mixin which adds a successors handling step that checks if a syscall was just requested and if so handles it as a step.

class angr.engines.SimEngineUnicorn

Bases: SuccessorsEngine

Concrete execution in the Unicorn Engine, a fork of qemu.

Responds to the following parameters in the step stack:

  • step: How many basic blocks we want to execute

  • extra_stop_points: A collection of addresses at which execution should halt

__init__(project)
Parameters:

project (Project)

class angr.engines.SimInspectMixin

Bases: VEXMixin

handle_vex_block(irsb)
class angr.engines.SimSuccessors

Bases: object

This class serves as a categorization of all the kinds of result states that can come from a SimEngine run.

Variables:

  • addr (int) – The address at which execution is taking place, as a python int

  • initial_state – The initial state for which execution produced these successors

  • engine – The engine that produced these successors

  • sort (str | None) – A string identifying the type of engine that produced these successors

  • processed (bool) – Whether or not the processing succeeded

  • description (str) – A textual description of the execution step

The successor states produced by this run are categorized into several lists:

Variables:

  • artifacts (dict) – Any analysis byproducts (for example, an IRSB) that were produced during execution

  • successors (list[SimState[int | SootAddressDescriptor, claripy.ast.BV | SootAddressDescriptor]]) – The “normal” successors. IP may be symbolic, but must have reasonable number of solutions

  • unsat_successors (list[SimState[int | SootAddressDescriptor, claripy.ast.BV | SootAddressDescriptor]]) – Any successor which is unsatisfiable after its guard condition is added.

  • all_successors (list[SimState[int | SootAddressDescriptor, claripy.ast.BV | SootAddressDescriptor]]) – successors + unsat_successors

  • flat_successors (list[SimState[int | SootAddressDescriptor, claripy.ast.BV | SootAddressDescriptor]]) – The normal successors, but any symbolic IPs have been concretized. There is one state in this list for each possible value an IP may be concretized to for each successor state.

  • unconstrained_successors (list[SimState[int | SootAddressDescriptor, claripy.ast.BV | SootAddressDescriptor]]) – Any state for which during the flattening process we find too many solutions.

A more detailed description of the successor lists may be found here: https://docs.angr.io/core-concepts/simulation#simsuccessors

__init__(addr, initial_state)
Parameters:
property is_empty
add_successor(state, target, guard, jumpkind, add_guard=True, exit_stmt_idx=None, exit_ins_addr=None, source=None)

Add a successor state of the SimRun. This procedure stores method parameters into state.scratch, does some housekeeping, and calls out to helper functions to prepare the state and categorize it into the appropriate successor lists.

Parameters:

  • state (SimState) – The successor state.

  • target – The target (of the jump/call/ret).

  • guard – The guard expression.

  • jumpkind (str) – The jumpkind (call, ret, jump, or whatnot).

  • add_guard (bool) – Whether to add the guard constraint (default: True).

  • exit_stmt_idx (int) – The ID of the exit statement, an integer by default. ‘default’ stands for the default exit, and None means it’s not from a statement (for example, from a SimProcedure).

  • exit_ins_addr (int) – The instruction pointer of this exit, which is an integer by default.

  • source (int) – The source of the jump (i.e., the address of the basic block).

class angr.engines.SootMixin

Bases: SuccessorsEngine, ProcedureMixin

Execution engine based on Soot.

lift_soot(addr=None, the_binary=None, **kwargs)
get_unconstrained_simprocedure()
classmethod setup_callsite(state, args, ret_addr, ret_var=None)
static setup_arguments(state, args)
static prepare_return_state(state, ret_value=None)
static terminate_execution(statement, state, successors)
static prepare_native_return_state(native_state)

Hook target for native function call returns.

Recovers and stores the return value from native memory and toggles the state, s.t. execution continues in the Soot engine.

class angr.engines.SuccessorsEngine

Bases: SimEngine[HeavyState, SimSuccessors]

A mixin for SimEngine which implements process to perform common operations related to symbolic execution and dispatches to a process_successors method to fill a SimSuccessors object with the results.

__init__(project)
Parameters:

project (Project)

process(state, **kwargs)

Perform execution with a state.

You should only override this method in a subclass in order to provide the correct method signature and docstring. You should override the _process method to do your actual execution.

Parameters:

  • state (SimState[int | SootAddressDescriptor, claripy.ast.BV | SootAddressDescriptor]) – The state with which to execute. This state will be copied before modification.

  • inline – This is an inline execution. Do not bother copying the state.

  • force_addr – Force execution to pretend that we’re working at this concrete address

Return type:

SimSuccessors

Returns:

A SimSuccessors object categorizing the execution’s successor states

process_successors(successors, **kwargs)

Implement this function to fill out the SimSuccessors object with the results of stepping state.

In order to implement a model where multiple mixins can potentially handle a request, a mixin may implement this method and then perform a super() call if it wants to pass on handling to the next mixin.

Keep in mind python’s method resolution order when composing multiple classes implementing this method. In short: left-to-right, depth-first, but deferring any base classes which are shared by multiple subclasses (the merge point of a diamond pattern in the inheritance graph) until the last point where they would be encountered in this depth-first search. For example, if you have classes A, B(A), C(B), D(A), E(C, D), then the method resolution order will be E, C, B, D, A.

Parameters:

  • state – The state to manipulate

  • successors (SimSuccessors) – The successors object to fill out

  • kwargs – Any extra arguments. Do not fail if you are passed unexpected arguments.

class angr.engines.SuperFastpathMixin

Bases: VEXSlicingMixin

This mixin implements the superfastpath execution mode, which skips all but the last four instructions.

handle_vex_block(irsb)
class angr.engines.TrackActionsMixin

Bases: HeavyVEXMixin

__init__(*args, **kwargs)
handle_vex_block(irsb)
class angr.engines.UberEngine

Bases: SimEngineFailure, SimEngineSyscall, HooksMixin, SimEngineUnicorn, SuperFastpathMixin, TrackActionsMixin, SimInspectMixin, HeavyResilienceMixin, SootMixin, AILMixin, HeavyVEXMixin

The default execution engine for angr. This engine includes mixins for most common functionality in angr, including VEX IR, unicorn, syscall handling, and simprocedure handling.

For some performance-sensitive applications, you may want to create a custom engine with only the necessary mixins.

class angr.engines.UberEnginePcode

Bases: SimEngineFailure, SimEngineSyscall, HooksMixin, HeavyPcodeMixin

Submodules

ail

engine

failure

hook

icicle

icicle.py: An angr engine that uses Icicle to execute code.

light

pcode

procedure

soot

successors

syscall

unicorn

vex