Engines API

Execution engines for binary analysis and symbolic execution in angr

angr’s execution engines are responsible for taking a state and producing successor states. The engine system is modular, with base classes and mixins that can be composed to create custom execution engines.

SimEngine

The base class for all execution engines.

class SimEngine(Generic[StateType, ResultType], metaclass=abc.ABCMeta)

project · angr.Project · required

The angr project this engine belongs to

Attributes

project · angr.Project

The associated angr project

arch · archinfo.Arch

The architecture being analyzed (derived from project.arch)

state · StateType

The current state being executed

---

SimSuccessors

Categorizes all result states from a SimEngine run.

class SimSuccessors:
    def __init__(self, addr: int | AILAddr | SootAddressDescriptor | None,
                 initial_state: SimState | None)

addr · int | AILAddr | SootAddressDescriptor

The address at which execution is taking place

initial_state · SimState

The initial state for which execution produced these successors

Attributes

successors · list[SimState]

The “normal” successors. IP may be symbolic, but must have reasonable number of solutions

flat_successors · list[SimState]

Normal successors with symbolic IPs concretized. One state per possible IP value

unsat_successors · list[SimState]

Successors that are unsatisfiable after guard condition is added

unconstrained_successors · list[SimState]

States with too many possible IP solutions during flattening

all_successors · list[SimState]

All successors (successors + unsat_successors)

engine · SimEngine

The engine that produced these successors

processed · bool

Whether processing succeeded

artifacts · dict

Analysis byproducts (e.g., IRSB) produced during execution

Methods

add_successor

Add a successor state to the appropriate list.

def add_successor(self, state: SimState, target, guard, jumpkind: str,
                   add_guard: bool = True, exit_stmt_idx=None,
                   exit_ins_addr=None, source=None)

state · SimState · required

The successor state

target · BV | int

The target address of the jump/call/ret

guard · BV

The guard expression for this successor

jumpkind · str · required

Type of jump: ‘Ijk_Call’, ‘Ijk_Ret’, ‘Ijk_Boring’, ‘Ijk_Sys*’, etc.

add_guard · bool · default: "True"

Whether to add the guard constraint to the state

exit_stmt_idx · int

The ID of the exit statement (‘default’ for default exit, None for non-statement exits)

exit_ins_addr · int

The instruction pointer of this exit

source · int

The source address of the jump (basic block address)

---

SuccessorsEngine

Mixin for engines that produce SimSuccessors objects.

class SuccessorsEngine(SimEngine[HeavyState, SimSuccessors])

Methods

process

Perform execution with a state.

def process(self, state: SimState, inline: bool = False,
            force_addr: int | None = None, **kwargs) -> SimSuccessors

state · SimState · required

The state to execute. Will be copied before modification unless inline=True

inline · bool · default: "False"

Don’t copy the state before execution

force_addr · int

Force execution to pretend we’re at this concrete address

Returns a SimSuccessors object categorizing the execution’s successor states.

process_successors

Override this method to fill out the SimSuccessors object.

def process_successors(self, successors: SimSuccessors, **kwargs)

successors · SimSuccessors · required

The successors object to fill with results

---

UberEngine

The default execution engine for angr.

class UberEngine(
    SimEngineFailure,
    SimEngineSyscall,
    HooksMixin,
    SimEngineUnicorn,
    SuperFastpathMixin,
    TrackActionsMixin,
    SimInspectMixin,
    HeavyResilienceMixin,
    SootMixin,
    AILMixin,
    HeavyVEXMixin,
)

Includes mixins for most common functionality:

• VEX IR execution - Execute VEX intermediate representation
• Unicorn - Concrete execution using Unicorn Engine
• Syscall handling - Process system calls
• Hook support - Execute user-defined hooks
• SimProcedure handling - Execute symbolic procedure summaries
• Action tracking - Record memory/register operations
• Inspection - Breakpoint and instrumentation support

For performance-sensitive applications, create a custom engine with only necessary mixins.

---

HeavyVEXMixin

Execution engine based on VEX (Valgrind’s IR).

class HeavyVEXMixin(SuccessorsEngine, ClaripyDataMixin,
                    SimStateStorageMixin, VEXMixin, VEXLifter)

Step Parameters

Responds to the following keyword arguments in step():

irsb · pyvex.IRSB

PyVEX IRSB object to use for execution. If not provided, one will be lifted

skip_stmts · int

Number of statements to skip in processing

last_stmt · int

Do not execute any statements after this statement

whitelist · set[int]

Only execute statements in this set

thumb · bool

Force block to be lifted in ARM’s THUMB mode

extra_stop_points · set[int]

Additional addresses at which to break basic blocks

opt_level · int

VEX optimization level (0-2)

insn_bytes · bytes

Bytes to use for the block instead of reading from project

size · int

Maximum size of the block in bytes

num_inst · int

Maximum number of instructions to execute

traceflags · int · default: "0"

VEX trace flags for debugging

---

SimEngineSyscall

Engine mixin for handling system calls.

class SimEngineSyscall(SuccessorsEngine)

Automatically dispatches to the appropriate syscall SimProcedure based on the syscall number in the state.

---

SimEngineUnicorn

Engine for concrete execution using Unicorn Engine.

class SimEngineUnicorn(SuccessorsEngine)

Provides fast concrete execution when state is fully concrete. Falls back to symbolic execution when symbolic values are encountered.

Example: Using Different Engines

import angr

# Load binary
project = angr.Project('/bin/ls', auto_load_libs=False)

# Create initial state
state = project.factory.entry_state()

# Use default UberEngine (automatic)
simgr = project.factory.simulation_manager(state)
simgr.step()

# Access successors
for successor in simgr.active:
    print(f"State at: {hex(successor.addr)}")

# Use Unicorn for concrete execution
state.options.add(angr.options.UNICORN)
simgr2 = project.factory.simulation_manager(state)
simgr2.run(until=lambda sm: len(sm.active) > 1)

# Custom step with VEX parameters
simgr.step(
    num_inst=10,        # Execute max 10 instructions
    opt_level=1,        # VEX optimization level
)

Example: Accessing Execution Artifacts

import angr

project = angr.Project('/bin/example')
state = project.factory.entry_state()

# Get successors object
successors = project.factory.successors(state)

# Access IRSB artifact
irsb = successors.artifacts['irsb']
print(f"IRSB at {hex(irsb.addr)}")
print(f"IRSB size: {successors.artifacts['irsb_size']} bytes")
print(f"Instruction addresses: {[hex(a) for a in successors.artifacts['insn_addrs']]}")

# Examine successors
print(f"Normal successors: {len(successors.flat_successors)}")
print(f"Unsat successors: {len(successors.unsat_successors)}")
print(f"Unconstrained: {len(successors.unconstrained_successors)}")

---

Engine Composition

Create custom engines by composing mixins:

from angr.engines import (
    SuccessorsEngine,
    HeavyVEXMixin,
    HooksMixin,
    SimInspectMixin
)

# Minimal engine: VEX + hooks + inspection
class MinimalEngine(
    HooksMixin,
    SimInspectMixin,
    HeavyVEXMixin
):
    pass

# Use custom engine
project = angr.Project('/bin/ls')
project.factory.default_engine = MinimalEngine

Mixins are resolved left-to-right using Python’s MRO (Method Resolution Order).