angr.engines.successors

class angr.engines.successors.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).

type angr.engines.successors.HeavyState = SimState[int | SootAddressDescriptor, claripy.ast.BV | SootAddressDescriptor]
class angr.engines.successors.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.