SimulationManager

Manage multiple states during symbolic execution with stashes and exploration techniques

The SimulationManager (also called simgr) allows you to wrangle multiple states in a slick way. States are organized into “stashes”, which you can step forward, filter, merge, and move around as you wish.

Class Signature

class SimulationManager:
    def __init__(
        self,
        project,
        active_states=None,
        stashes=None,
        hierarchy=None,
        resilience=None,
        save_unsat=False,
        auto_drop=None,
        errored=None,
        completion_mode=any,
        techniques=None,
        suggestions=True,
        **kwargs,
    )

Parameters

project · Project

The angr Project instance.

active_states · list[SimState]

Active states to seed the “active” stash with.

stashes · dict[str, list[SimState]]

A dictionary to use as the stash store.

hierarchy · StateHierarchy

A StateHierarchy object to track relationships between states.

resilience · tuple | bool | None · default: "None"

A set of errors to catch during stepping. False: catch no errors. None: catch angr-specific errors. True: catch many common errors.

save_unsat · bool · default: "False"

If True, introduce unsatisfiable states into the unsat stash instead of discarding them.

auto_drop · set[str]

A set of stash names which should be treated as garbage chutes.

completion_mode · Callable · default: "any"

A function describing how multiple exploration techniques with the complete hook set will interact.

techniques · list[ExplorationTechnique]

A list of techniques that should be pre-set to use with this manager.

suggestions · bool · default: "True"

Whether to automatically install the Suggestions exploration technique.

Attributes

active · list[SimState]

The active stash containing states being actively explored.

stashed · list[SimState]

States that have been temporarily stashed.

deadended · list[SimState]

States that have reached a deadend (no successors).

errored · list[ErrorRecord]

A list of ErrorRecord objects for states that encountered errors.

unsat · list[SimState]

States with unsatisfiable constraints.

unconstrained · list[SimState]

States with unconstrained instruction pointers.

pruned · list[SimState]

States that have been pruned.

stashes · defaultdict[str, list[SimState]]

Dictionary of all stashes.

Constants

ALL · str · default: "_ALL"

Special stash name referring to all stashes.

DROP · str · default: "_DROP"

Special stash name for dropping states.

Methods

Core Execution

step()

Signature:

def step(
    self,
    stash="active",
    target_stash=None,
    n=None,
    selector_func=None,
    step_func=None,
    error_list=None,
    successor_func=None,
    until=None,
    filter_func=None,
    **run_args,
) -> SimulationManager

Step a stash of states forward and categorize the successors appropriately.

Parameters:

stash · str · default: "active"

The name of the stash to step.

target_stash · str

The name of the stash to put results in (defaults to same as stash).

selector_func · Callable[[SimState], bool]

If provided, only step states where this returns True.

step_func · Callable[[SimulationManager], SimulationManager]

A maintenance function called after each step.

successor_func · Callable[[SimState], SimSuccessors]

Custom function to generate successors for a state.

filter_func · Callable[[SimState], str]

Function that returns the stash name for each state.

Returns: SimulationManager - Self, for chaining.

run()

Signature:

def run(
    self,
    stash="active",
    n=None,
    until=None,
    **kwargs
) -> SimulationManager

Run until the SimulationManager has reached a completed state or until there is nothing left to run.

Parameters:

stash · str · default: "active"

Operate on this stash.

n · int

Step at most this many times.

until · Callable[[SimulationManager], bool]

A function that takes a SimulationManager and returns True when stepping should terminate.

Returns: SimulationManager - Self, for chaining.

explore()

Signature:

def explore(
    self,
    stash="active",
    n=None,
    find=None,
    avoid=None,
    find_stash="found",
    avoid_stash="avoid",
    cfg=None,
    num_find=1,
    avoid_priority=False,
    **kwargs,
) -> SimulationManager

Tick stash forward, looking for states that match find and avoiding states that match avoid.

Parameters:

stash · str · default: "active"

The stash to explore.

n · int

Maximum number of steps.

find · int | list[int] | Callable[[SimState], bool]

An address, list of addresses, or function to identify found states.

avoid · int | list[int] | Callable[[SimState], bool]

An address, list of addresses, or function to identify states to avoid.

find_stash · str · default: "found"

Stash to put found states in.

avoid_stash · str · default: "avoid"

Stash to put avoided states in.

num_find · int · default: "1"

Explore until this many states are found.

Returns: SimulationManager - Self, for chaining.

Exploration Techniques

use_technique()

Signature:

def use_technique(self, tech: ExplorationTechnique) -> ExplorationTechnique

Use an exploration technique with this SimulationManager.

Parameters:

tech · ExplorationTechnique

An ExplorationTechnique object that modifies the SimulationManager’s behavior.

Returns: ExplorationTechnique - The technique that was added.

remove_technique()

Signature:

def remove_technique(self, tech: ExplorationTechnique) -> ExplorationTechnique

Remove an exploration technique from the list of active techniques.

Parameters:

tech · ExplorationTechnique

The ExplorationTechnique to remove.

Returns: ExplorationTechnique - The removed technique.

State Management

move()

Signature:

def move(
    self,
    from_stash: str,
    to_stash: str,
    filter_func: Callable[[SimState], bool] | None = None
) -> SimulationManager

Move states from one stash to another.

Parameters:

from_stash · str

Take matching states from this stash.

to_stash · str

Put matching states into this stash.

filter_func · Callable[[SimState], bool]

Function that returns True for states to move.

Returns: SimulationManager - Self, for chaining.

stash()

Signature:

def stash(
    self,
    filter_func=None,
    from_stash="active",
    to_stash="stashed"
) -> SimulationManager

Stash some states. Alias for move() with default stashes.

Parameters:

filter_func · Callable[[SimState], bool]

Stash states where this returns True.

from_stash · str · default: "active"

Take states from this stash.

to_stash · str · default: "stashed"

Put states into this stash.

Returns: SimulationManager - Self, for chaining.

unstash()

Signature:

def unstash(
    self,
    filter_func=None,
    to_stash="active",
    from_stash="stashed"
) -> SimulationManager

Unstash some states. Alias for move() with default stashes.

Parameters:

filter_func · Callable[[SimState], bool]

Unstash states where this returns True.

from_stash · str · default: "stashed"

Take states from this stash.

to_stash · str · default: "active"

Put states into this stash.

Returns: SimulationManager - Self, for chaining.

drop()

Signature:

def drop(
    self,
    filter_func=None,
    stash="active"
) -> SimulationManager

Drop states from a stash.

Parameters:

filter_func · Callable[[SimState], bool]

Drop states where this returns True.

stash · str · default: "active"

Drop from this stash.

Returns: SimulationManager - Self, for chaining.

prune()

Signature:

def prune(
    self,
    filter_func=None,
    from_stash="active",
    to_stash="pruned"
) -> SimulationManager

Prune unsatisfiable states from a stash.

Parameters:

filter_func · Callable[[SimState], bool]

Only prune states matching this filter.

from_stash · str · default: "active"

Prune from this stash.

to_stash · str · default: "pruned"

Put pruned states here.

Returns: SimulationManager - Self, for chaining.

merge()

Signature:

def merge(
    self,
    merge_func=None,
    merge_key=None,
    stash="active",
    prune=True
) -> SimulationManager

Merge states in a given stash.

Parameters:

merge_func · Callable

Custom merge function (uses state.merge by default).

merge_key · Callable[[SimState], Any]

Function returning a key for grouping mergeable states.

stash · str · default: "active"

The stash to merge.

prune · bool · default: "True"

Whether to prune before merging.

Returns: SimulationManager - Self, for chaining.

Utility Methods

apply()

Signature:

def apply(
    self,
    state_func=None,
    stash_func=None,
    stash="active",
    to_stash=None
) -> SimulationManager

Apply a function to states or an entire stash.

Parameters:

state_func · Callable[[SimState], SimState | list[SimState]]

Function to apply to each state.

stash_func · Callable[[list[SimState]], list[SimState]]

Function to apply to the whole stash.

stash · str · default: "active"

Stash to work with.

to_stash · str

Store results in this stash.

Returns: SimulationManager - Self, for chaining.

split()

Signature:

def split(
    self,
    stash_splitter=None,
    stash_ranker=None,
    state_ranker=None,
    limit=8,
    from_stash="active",
    to_stash="stashed",
) -> SimulationManager

Split a stash into two based on various criteria.

Parameters:

stash_splitter · Callable[[list[SimState]], tuple[list, list]]

Function that splits the stash into two lists.

stash_ranker · Callable[[list[SimState]], list[SimState]]

Function that ranks states (first limit kept).

state_ranker · Callable[[SimState], Any]

Function providing sort key for states.

limit · int · default: "8"

Number of states to keep.

Returns: SimulationManager - Self, for chaining.

populate()

Signature:

def populate(self, stash: str, states: list[SimState]) -> SimulationManager

Populate a stash with a collection of states.

Parameters:

stash · str

The stash to populate.

states · list[SimState]

States to add to the stash.

Returns: SimulationManager - Self, for chaining.

copy()

Signature:

def copy(self, deep=False) -> SimulationManager

Make a copy of this simulation manager.

Parameters:

deep · bool · default: "False"

If True, copy all states as well.

Returns: SimulationManager - A copy of this manager.

complete()

Signature:

def complete(self) -> bool

Check if the manager has reached a “completed” state according to active exploration techniques.

Returns: bool - True if complete, False otherwise.

ErrorRecord Class

class ErrorRecord:
    state: SimState
    error: Exception
    traceback: TracebackType

debug()

Launch a postmortem debug shell at the site of the error.

reraise()

Re-raise the error with its original traceback.

Example Usage

import angr

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

# Create a simulation manager
simgr = proj.factory.simulation_manager()

# Step execution
simgr.step()
print(f"Active states: {len(simgr.active)}")

# Explore to find a specific address
simgr.explore(find=0x400000, avoid=[0x400100, 0x400200])

if simgr.found:
    found_state = simgr.found[0]
    print(f"Found state at {found_state.addr:#x}")

# Use stashes
simgr.stash(filter_func=lambda s: s.addr == 0x400300)
simgr.unstash()

# Apply function to all states
def print_addr(state):
    print(f"State at {state.addr:#x}")
    return state

simgr.apply(state_func=print_addr)

# Use exploration technique
from angr.exploration_techniques import DFS
simgr.use_technique(DFS())
simgr.run()

# Handle errors
if simgr.errored:
    for err in simgr.errored:
        print(f"Error: {err.error}")
        print(f"State: {err.state}")