angr.sim_manager

class angr.sim_manager.SimulationManager

Bases: object

The Simulation Manager is the future future.

Simulation managers allow 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. This allows you to, for example, step two different stashes of states at different rates, then merge them together.

Stashes can be accessed as attributes (i.e. .active). A mulpyplexed stash can be retrieved by prepending the name with mp_, e.g. .mp_active. A single state from the stash can be retrieved by prepending the name with one_, e.g. .one_active.

Note that you shouldn’t usually be constructing SimulationManagers directly - there is a convenient shortcut for creating them in Project.factory: see angr.factory.AngrObjectFactory.

The most important methods you should look at are step, explore, and use_technique.

Parameters:

  • project (angr.project.Project) – A Project instance.

  • stashes – A dictionary to use as the stash store.

  • active_states – Active states to seed the “active” stash with.

  • hierarchy – A StateHierarchy object to use to track the relationships between states.

  • resilience – A set of errors to catch during stepping to put a state in the errore list. You may also provide the values False, None (default), or True to catch, respectively, no errors, all angr-specific errors, and a set of many common errors.

  • save_unsat – Set to True in order to introduce unsatisfiable states into the unsat stash instead of discarding them immediately.

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

  • completion_mode – A function describing how multiple exploration techniques with the complete hook set will interact. By default, the builtin function any.

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

  • suggestions – Whether to automatically install the Suggestions exploration technique. Default True.

Variables:

  • errored – Not a stash, but a list of ErrorRecords. Whenever a step raises an exception that we catch, the state and some information about the error are placed in this list. You can adjust the list of caught exceptions with the resilience parameter.

  • stashes – All the stashes on this instance, as a dictionary.

  • completion_mode – A function describing how multiple exploration techniques with the complete hook set will interact. By default, the builtin function any.

ALL = '_ALL'
DROP = '_DROP'
__init__(project, active_states=None, stashes=None, hierarchy=None, resilience=None, save_unsat=False, auto_drop=None, errored=None, completion_mode=<built-in function any>, techniques=None, suggestions=True, **kwargs)
active: list[SimState]
stashed: list[SimState]
pruned: list[SimState]
unsat: list[SimState]
deadended: list[SimState]
unconstrained: list[SimState]
found: list[SimState]
one_active: SimState
one_stashed: SimState
one_pruned: SimState
one_unsat: SimState
one_deadended: SimState
one_unconstrained: SimState
one_found: SimState
property errored: list[ErrorRecord]
property stashes: defaultdict[str, list[SimState]]
mulpyplex(*stashes)

Mulpyplex across several stashes.

Parameters:

stashes – the stashes to mulpyplex

Returns:

a mulpyplexed list of states from the stashes in question, in the specified order

copy(deep=False)

Make a copy of this simulation manager. Pass deep=True to copy all the states in it as well.

If the current callstack includes hooked methods, the already-called methods will not be included in the copy.

use_technique(tech)

Use an exploration technique with this SimulationManager.

Techniques can be found in angr.exploration_techniques.

Parameters:

tech (ExplorationTechnique) – An ExplorationTechnique object that contains code to modify this SimulationManager’s behavior.

Returns:

The technique that was added, for convenience

remove_technique(tech)

Remove an exploration technique from a list of active techniques.

Parameters:

tech (ExplorationTechnique) – An ExplorationTechnique object.

explore(stash='active', n=None, find=None, avoid=None, find_stash='found', avoid_stash='avoid', cfg=None, num_find=1, avoid_priority=False, **kwargs)

Tick stash “stash” forward (up to “n” times or until “num_find” states are found), looking for condition “find”, avoiding condition “avoid”. Stores found states into “find_stash’ and avoided states into “avoid_stash”.

The “find” and “avoid” parameters may be any of:

  • An address to find

  • A set or list of addresses to find

  • A function that takes a state and returns whether or not it matches.

If an angr CFG is passed in as the “cfg” parameter and “find” is either a number or a list or a set, then any states which cannot possibly reach a success state without going through a failure state will be preemptively avoided.

run(stash='active', n=None, until=None, **kwargs)

Run until the SimulationManager has reached a completed state, according to the current exploration techniques. If no exploration techniques that define a completion state are being used, run until there is nothing left to run.

Parameters:

  • stash – Operate on this stash

  • n – Step at most this many times

  • until – If provided, should be a function that takes a SimulationManager and returns True or False. Stepping will terminate when it is True.

Returns:

The simulation manager, for chaining.

Return type:

SimulationManager

complete()

Returns whether or not this manager has reached a “completed” state.

step(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)

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

The parameters to this function allow you to control everything about the stepping and categorization process.

Parameters:

  • stash – The name of the stash to step (default: ‘active’)

  • target_stash – The name of the stash to put the results in (default: same as stash)

  • error_list – The list to put ErrorRecord objects in (default: self.errored)

  • selector_func – If provided, should be a function that takes a state and returns a boolean. If True, the state will be stepped. Otherwise, it will be kept as-is.

  • step_func – If provided, should be a function that takes a SimulationManager and returns a SimulationManager. Will be called with the SimulationManager at every step. Note that this function should not actually perform any stepping - it is meant to be a maintenance function called after each step.

  • successor_func – If provided, should be a function that takes a state and return its successors. Otherwise, project.factory.successors will be used.

  • filter_func – If provided, should be a function that takes a state and return the name of the stash, to which the state should be moved.

  • until – (DEPRECATED) If provided, should be a function that takes a SimulationManager and returns True or False. Stepping will terminate when it is True.

  • n – (DEPRECATED) The number of times to step (default: 1 if “until” is not provided)

Additionally, you can pass in any of the following keyword args for project.factory.successors:

Parameters:

  • jumpkind – The jumpkind of the previous exit

  • addr – An address to execute at instead of the state’s ip.

  • stmt_whitelist – A list of stmt indexes to which to confine execution.

  • last_stmt – A statement index at which to stop execution.

  • thumb – Whether the block should be lifted in ARM’s THUMB mode.

  • backup_state – A state to read bytes from instead of using project memory.

  • 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

Returns:

The simulation manager, for chaining.

Return type:

SimulationManager

step_state(state, successor_func=None, error_list=None, **run_args)

Don’t use this function manually - it is meant to interface with exploration techniques.

filter(state, filter_func=None)

Don’t use this function manually - it is meant to interface with exploration techniques.

selector(state, selector_func=None)

Don’t use this function manually - it is meant to interface with exploration techniques.

successors(state, successor_func=None, **run_args)

Don’t use this function manually - it is meant to interface with exploration techniques.

prune(filter_func=None, from_stash='active', to_stash='pruned')

Prune unsatisfiable states from a stash.

This function will move all unsatisfiable states in the given stash into a different stash.

Parameters:

  • filter_func – Only prune states that match this filter.

  • from_stash – Prune states from this stash. (default: ‘active’)

  • to_stash – Put pruned states in this stash. (default: ‘pruned’)

Returns:

The simulation manager, for chaining.

Return type:

SimulationManager

populate(stash, states)

Populate a stash with a collection of states.

Parameters:

  • stash – A stash to populate.

  • states – A list of states with which to populate the stash.

absorb(simgr)

Collect all the states from simgr and put them in their corresponding stashes in this manager. This will not modify simgr.

move(from_stash, to_stash, filter_func=None)

Move states from one stash to another.

Parameters:

  • from_stash – Take matching states from this stash.

  • to_stash – Put matching states into this stash.

  • filter_func – Stash states that match this filter. Should be a function that takes a state and returns True or False. (default: stash all states)

Returns:

The simulation manager, for chaining.

Return type:

SimulationManager

stash(filter_func=None, from_stash='active', to_stash='stashed')

Stash some states. This is an alias for move(), with defaults for the stashes.

Parameters:

  • filter_func – Stash states that match this filter. Should be a function that takes a state and returns True or False. (default: stash all states)

  • from_stash – Take matching states from this stash. (default: ‘active’)

  • to_stash – Put matching states into this stash. (default: ‘stashed’)

Returns:

The simulation manager, for chaining.

Return type:

SimulationManager

unstash(filter_func=None, to_stash='active', from_stash='stashed')

Unstash some states. This is an alias for move(), with defaults for the stashes.

Parameters:

  • filter_func – Unstash states that match this filter. Should be a function that takes a state and returns True or False. (default: unstash all states)

  • from_stash – take matching states from this stash. (default: ‘stashed’)

  • to_stash – put matching states into this stash. (default: ‘active’)

Returns:

The simulation manager, for chaining.

Return type:

SimulationManager

drop(filter_func=None, stash='active')

Drops states from a stash. This is an alias for move(), with defaults for the stashes.

Parameters:

  • filter_func – Drop states that match this filter. Should be a function that takes a state and returns True or False. (default: drop all states)

  • stash – Drop matching states from this stash. (default: ‘active’)

Returns:

The simulation manager, for chaining.

Return type:

SimulationManager

apply(state_func=None, stash_func=None, stash='active', to_stash=None)

Applies a given function to a given stash.

Parameters:

  • state_func – A function to apply to every state. Should take a state and return a state. The returned state will take the place of the old state. If the function doesn’t return a state, the old state will be used. If the function returns a list of states, they will replace the original states.

  • stash_func – A function to apply to the whole stash. Should take a list of states and return a list of states. The resulting list will replace the stash. If both state_func and stash_func are provided state_func is applied first, then stash_func is applied on the results.

  • stash – A stash to work with.

  • to_stash – If specified, this stash will be used to store the resulting states instead.

Returns:

The simulation manager, for chaining.

Return type:

SimulationManager

split(stash_splitter=None, stash_ranker=None, state_ranker=None, limit=8, from_stash='active', to_stash='stashed')

Split a stash of states into two stashes depending on the specified options.

The stash from_stash will be split into two stashes depending on the other options passed in. If to_stash is provided, the second stash will be written there.

stash_splitter overrides stash_ranker, which in turn overrides state_ranker. If no functions are provided, the states are simply split according to the limit.

The sort done with state_ranker is ascending.

Parameters:

  • stash_splitter – A function that should take a list of states and return a tuple of two lists (the two resulting stashes).

  • stash_ranker – A function that should take a list of states and return a sorted list of states. This list will then be split according to “limit”.

  • state_ranker – An alternative to stash_splitter. States will be sorted with outputs of this function, which are to be used as a key. The first “limit” of them will be kept, the rest split off.

  • limit – For use with state_ranker. The number of states to keep. Default: 8

  • from_stash – The stash to split (default: ‘active’)

  • to_stash – The stash to write to (default: ‘stashed’)

Returns:

The simulation manager, for chaining.

Return type:

SimulationManager

merge(merge_func=None, merge_key=None, stash='active', prune=True)

Merge the states in a given stash.

Parameters:

  • stash – The stash (default: ‘active’)

  • merge_func – If provided, instead of using state.merge, call this function with the states as the argument. Should return the merged state.

  • merge_key – If provided, should be a function that takes a state and returns a key that will compare equal for all states that are allowed to be merged together, as a first approximation. By default: uses PC, callstack, and open file descriptors.

  • prune – Whether to prune the stash prior to merging it

Returns:

The simulation manager, for chaining.

Return type:

SimulationManager

class angr.sim_manager.ErrorRecord

Bases: object

A container class for a state and an error that was thrown during its execution. You can find these in SimulationManager.errored.

Variables:

  • state (SimState) – The state that encountered an error, at the point in time just before the erroring step began.

  • error (Exception) – The error that was thrown.

  • traceback (TracebackType) – The traceback for the error that was thrown.

__init__(state, error, traceback)
state: SimState
error: Exception
traceback: TracebackType
debug()

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

reraise()