SimState

Represents the state of a program including memory, registers, and constraints

The SimState class represents the state of a program at a particular point in execution, including its memory, registers, symbolic constraints, and execution history.

Class Signature

class SimState(Generic[IPTypeConc, IPTypeSym], PluginHub[SimStatePlugin]):
    def __init__(
        self,
        project: Project | None = None,
        arch: Arch | None = None,
        plugins: dict[str, SimStatePlugin] | None = None,
        mode: str | None = None,
        options: set[str] | list[str] | SimStateOptions | None = None,
        add_options: set[str] | None = None,
        remove_options: set[str] | None = None,
        special_memory_filler: Callable[[str, int, int, SimState], Any] | None = None,
        os_name: str | None = None,
        plugin_preset: str = "default",
        cle_memory_backer: Clemory | None = None,
        dict_memory_backer: dict[int, bytes] | None = None,
        permissions_map: dict[tuple[int, int], int] | None = None,
        default_permissions: int = 3,
        stack_perms: int | None = None,
        stack_end: int | None = None,
        stack_size: int | None = None,
        regioned_memory_cls=None,
        **kwargs,
    )

Parameters

project · Project

The project instance.

arch · Arch | str

The architecture of the state.

plugins · dict[str, SimStatePlugin]

A dictionary of plugins to register with the state.

mode · str

The execution mode (e.g., ‘symbolic’, ‘static’, ‘fastpath’). Defaults to ‘symbolic’.

options · set[str] | SimStateOptions

A set of options to control state behavior.

add_options · set[str]

Options to add to the default set.

remove_options · set[str]

Options to remove from the default set.

plugin_preset · str · default: "default"

The plugin preset to use.

cle_memory_backer · Clemory

A CLE memory object to back the state’s memory.

dict_memory_backer · dict[int, bytes]

A dictionary mapping addresses to bytes for memory backing.

permissions_map · dict[tuple[int, int], int]

A mapping from (start, end) address ranges to permission flags.

default_permissions · int · default: "3"

Default memory permissions (read=1, write=2, execute=4).

Attributes

regs · SimRegNameView

A convenient view of the state’s registers, where each register is a property.

mem · SimMemView

A convenient view of the state’s memory.

registers · DefaultMemory

The state’s register file as a flat memory region.

memory · DefaultMemory

The state’s memory as a flat memory region.

solver · SimSolver

The symbolic solver and variable manager for this state.

inspect · SimInspector

The breakpoint manager for debugging and instrumentation.

history · SimStateHistory

Information about the state’s execution history.

scratch · SimStateScratch

Information about the current execution step.

posix · SimSystemPosix

POSIX/operating system environment model.

callstack · CallStack

The current call stack.

arch · Arch

The architecture of the state.

options · SimStateOptions

The set of options controlling state behavior.

mode · str

The execution mode.

Properties

Instruction Pointer Access

ip

Type: IPTypeSym

Get or set the instruction pointer expression. Triggers SimInspect breakpoints and generates SimActions.

For read-only access without triggering breakpoints, use _ip instead.

_ip

Type: IPTypeSym

Get or set the instruction pointer expression without triggering SimInspect breakpoints or generating SimActions.

addr

Type: IPTypeConc

Get or set the concrete address of the instruction pointer. Returns an integer, or raises an exception if the instruction pointer is symbolic.

Methods

State Manipulation

copy()

Signature:

def copy(self) -> SimState

Returns a deep copy of the state.

Returns: SimState - A new state that is a copy of this one.

merge()

Signature:

def merge(
    self,
    *others,
    merge_conditions=None,
    common_ancestor=None,
    plugin_whitelist=None,
    common_ancestor_history=None
) -> tuple[SimState, list, bool]

Merges this state with other states.

Parameters:

others · SimState

The states to merge with.

merge_conditions · list

A tuple of conditions under which each state holds.

common_ancestor · SimState

A state representing common history between the states.

plugin_whitelist · list[str]

Only merge plugins in this list.

Returns: tuple[SimState, list, bool] - (merged state, merge flag, whether merging occurred)

widen()

Signature:

def widen(self, *others) -> tuple[SimState, bool]

Perform a widening operation between this state and others.

Parameters:

others · SimState

States to widen with.

Returns: tuple[SimState, bool] - (widened state, whether widening occurred)

Constraint Management

add_constraints()

Signature:

def add_constraints(self, *constraints)

Add symbolic constraints to the state.

Parameters:

constraints · claripy.ast.Bool

Any number of symbolic boolean expressions to add as constraints.

satisfiable()

Signature:

def satisfiable(self, **kwargs) -> bool

Check whether the state’s constraints are satisfiable.

Returns: bool - True if satisfiable, False otherwise.

simplify()

Signature:

def simplify(self, *args)

Simplify this state’s constraints.

downsize()

Signature:

def downsize(self)

Clean up after the solver engine. Reduces memory usage when the state no longer needs to be solved.

Execution

step()

Signature:

def step(self, **kwargs) -> SimSuccessors

Perform a step of symbolic execution using this state.

Parameters: Any arguments to AngrObjectFactory.successors can be passed.

Returns: SimSuccessors - An object categorizing the results of the step.

block()

Signature:

def block(self, *args, **kwargs) -> Block

Represent the basic block at this state’s instruction pointer.

Parameters: Any arguments to AngrObjectFactory.block can be passed.

Returns: Block - A Block object describing the code at this point.

Register and Memory Access

reg_concrete()

Signature:

def reg_concrete(self, *args, **kwargs) -> int

Returns the contents of a register, raising SimValueError if symbolic.

Returns: int - The concrete value in the register.

mem_concrete()

Signature:

def mem_concrete(self, *args, **kwargs) -> int

Returns the contents of memory, raising SimValueError if symbolic.

Returns: int - The concrete value in memory.

Stack Operations

stack_push()

Signature:

def stack_push(self, thing)

Push a value to the stack, adjusting the stack pointer.

Parameters:

thing · claripy.ast.BV | int

The value to push onto the stack.

stack_pop()

Signature:

def stack_pop(self) -> claripy.ast.BV

Pop a value from the stack and return it. The length will be the architecture word size.

Returns: claripy.ast.BV - The popped value.

stack_read()

Signature:

def stack_read(self, offset: int, length: int, bp=False) -> claripy.ast.BV

Read bytes from the stack at an offset.

Parameters:

offset · int

The offset from the stack pointer.

length · int

The number of bytes to read.

bp · bool · default: "False"

If True, offset from BP instead of SP.

Returns: claripy.ast.BV - The value read from the stack.

Utility Methods

make_concrete_int()

Signature:

def make_concrete_int(self, expr) -> int

Force an expression to be concrete by adding a constraint.

Parameters:

expr · claripy.ast.BV | int

The expression to concretize.

Returns: int - The concrete value.

dbg_print_stack()

Signature:

def dbg_print_stack(self, depth=None, sp=None) -> str

Debug utility to print the current stack.

Parameters:

depth · int

Number of stack entries to print.

sp · int

Stack pointer value to use.

Returns: str - Formatted string representation of the stack.

set_mode()

Signature:

def set_mode(self, mode: str)

Change the execution mode of the state.

Parameters:

mode · str

The new mode (e.g., ‘symbolic’, ‘static’).

Example Usage

import angr
import claripy

proj = angr.Project('/bin/ls')

# Create a blank state
state = proj.factory.blank_state()

# Access registers
state.regs.rax = 0x1234
print(f"RAX = {state.regs.rax}")

# Create symbolic values
sym_arg = claripy.BVS('arg', 64)
state.regs.rdi = sym_arg

# Add constraints
state.add_constraints(sym_arg > 0)
state.add_constraints(sym_arg < 100)

# Check satisfiability
if state.satisfiable():
    possible_value = state.solver.eval(sym_arg)
    print(f"Possible value: {possible_value}")

# Memory operations
state.memory.store(0x1000, claripy.BVV(0xdeadbeef, 32))
value = state.memory.load(0x1000, 4)

# Stack operations
state.stack_push(claripy.BVV(0x42, 64))
popped = state.stack_pop()

# Copy state
state2 = state.copy()

# Step execution
successors = state.step()
for succ_state in successors.successors:
    print(f"Successor at {succ_state.addr:#x}")