angr.factory

class angr.factory.AngrObjectFactory

Bases: object

This factory provides access to important analysis elements.

__init__(project, default_engine=None)
Parameters:

default_engine (type[SimEngine] | None)

default_engine_factory: type[SimEngine]
project: Project
procedure_engine: ProcedureEngine
property default_engine
snippet(addr, jumpkind=None, **block_opts)
successors(*args, engine=None, **kwargs)

Perform execution using an engine. Generally, return a SimSuccessors object classifying the results of the run.

Parameters:

  • state – The state to analyze

  • engine – The engine to use. If not provided, will use the project default.

  • addr – optional, an address to execute at instead of the state’s ip

  • jumpkind – optional, the jumpkind of the previous exit

  • inline – This is an inline execution. Do not bother copying the state.

Additional keyword arguments will be passed directly into each engine’s process method.

blank_state(**kwargs)

Returns a mostly-uninitialized state object. All parameters are optional.

Parameters:

  • addr – The address the state should start at instead of the entry point.

  • initial_prefix – If this is provided, all symbolic registers will hold symbolic values with names prefixed by this string.

  • fs – A dictionary of file names with associated preset SimFile objects.

  • concrete_fs – bool describing whether the host filesystem should be consulted when opening files.

  • chroot – A path to use as a fake root directory, Behaves similarly to a real chroot. Used only when concrete_fs is set to True.

  • kwargs – Any additional keyword args will be passed to the SimState constructor.

Returns:

The blank state.

Return type:

SimState

entry_state(**kwargs)

Returns a state object representing the program at its entry point. All parameters are optional.

Parameters:

  • addr – The address the state should start at instead of the entry point.

  • initial_prefix – If this is provided, all symbolic registers will hold symbolic values with names prefixed by this string.

  • fs – a dictionary of file names with associated preset SimFile objects.

  • concrete_fs – boolean describing whether the host filesystem should be consulted when opening files.

  • chroot – a path to use as a fake root directory, behaves similar to a real chroot. used only when concrete_fs is set to True.

  • argc – a custom value to use for the program’s argc. May be either an int or a bitvector. If not provided, defaults to the length of args.

  • args – a list of values to use as the program’s argv. May be mixed strings and bitvectors.

  • env – a dictionary to use as the environment for the program. Both keys and values may be mixed strings and bitvectors.

Returns:

The entry state.

Return type:

SimState

full_init_state(**kwargs)

Very much like entry_state(), except that instead of starting execution at the program entry point, execution begins at a special SimProcedure that plays the role of the dynamic loader, calling each of the initializer functions that should be called before execution reaches the entry point.

It can take any of the arguments that can be provided to entry_state, except for addr.

call_state(addr, *args, **kwargs)

Returns a state object initialized to the start of a given function, as if it were called with given parameters.

Parameters:

  • addr – The address the state should start at instead of the entry point.

  • args – Any additional positional arguments will be used as arguments to the function call.

  • base_state – Use this SimState as the base for the new state instead of a blank state.

  • cc – Optionally provide a SimCC object to use a specific calling convention.

  • ret_addr – Use this address as the function’s return target.

  • stack_base – An optional pointer to use as the top of the stack, circa the function entry point

  • alloc_base – An optional pointer to use as the place to put excess argument data

  • grow_like_stack – When allocating data at alloc_base, whether to allocate at decreasing addresses

  • toc – The address of the table of contents for ppc64

  • initial_prefix – If this is provided, all symbolic registers will hold symbolic values with names prefixed by this string.

  • fs – A dictionary of file names with associated preset SimFile objects.

  • concrete_fs – bool describing whether the host filesystem should be consulted when opening files.

  • chroot – A path to use as a fake root directory, Behaves similarly to a real chroot. Used only when concrete_fs is set to True.

  • kwargs – Any additional keyword args will be passed to the SimState constructor.

Returns:

The state at the beginning of the function.

Return type:

SimState

The idea here is that you can provide almost any kind of python type in args and it’ll be translated to a binary format to be placed into simulated memory. Lists (representing arrays) must be entirely elements of the same type and size, while tuples (representing structs) can be elements of any type and size. If you’d like there to be a pointer to a given value, wrap the value in a SimCC.PointerWrapper. Any value that can’t fit in a register will be automatically put in a PointerWrapper.

If stack_base is not provided, the current stack pointer will be used, and it will be updated. If alloc_base is not provided, the current stack pointer will be used, and it will be updated. You might not like the results if you provide stack_base but not alloc_base.

grow_like_stack controls the behavior of allocating data at alloc_base. When data from args needs to be wrapped in a pointer, the pointer needs to point somewhere, so that data is dumped into memory at alloc_base. If you set alloc_base to point to somewhere other than the stack, set grow_like_stack to False so that sequential allocations happen at increasing addresses.

simulation_manager(thing=None, **kwargs)

Constructs a new simulation manager.

Parameters:

  • thing (list[SimState] | SimState | None) – What to put in the new SimulationManager’s active stash (either a SimState or a list of SimStates).

  • kwargs – Any additional keyword arguments will be passed to the SimulationManager constructor

Returns:

The new SimulationManager

Return type:

SimulationManager

Many different types can be passed to this method:

  • If nothing is passed in, the SimulationManager is seeded with a state initialized for the program entry point, i.e. entry_state().

  • If a SimState is passed in, the SimulationManager is seeded with that state.

  • If a list is passed in, the list must contain only SimStates and the whole list will be used to seed the SimulationManager.

simgr(*args, **kwargs)

Alias for simulation_manager to save our poor fingers

callable(addr, prototype=None, concrete_only=False, perform_merge=True, base_state=None, toc=None, cc=None, add_options=None, remove_options=None, techniques=None, step_limit=None)

A Callable is a representation of a function in the binary that can be interacted with like a native python function.

Parameters:

  • addr (int | Function) – The address of the function to use. If you pass in the function object, we will take its addr.

  • prototype – The prototype of the call to use, as a string or a SimTypeFunction

  • concrete_only – Throw an exception if the execution splits into multiple states

  • perform_merge – Merge all result states into one at the end (only relevant if concrete_only=False)

  • base_state – The state from which to do these runs

  • toc – The address of the table of contents for ppc64

  • cc – The SimCC to use for a calling convention

  • step_limit (int | None) – The maximum number of blocks that Callable will execute before pruning the path.

  • techniques (list[ExplorationTechnique] | None)

Returns:

A Callable object that can be used as a interface for executing guest code like a python function.

Return type:

angr.callable.Callable

cc()

Return a SimCC (calling convention) parameterized for this project.

Relevant subclasses of SimFunctionArgument are SimRegArg and SimStackArg, and shortcuts to them can be found on this cc object.

For stack arguments, offsets are relative to the stack pointer on function entry.

function_prototype()

Return a default function prototype parameterized for this project and SimOS.

block(addr, size=None, max_size=None, byte_string=None, thumb=False, backup_state=None, extra_stop_points=None, opt_level=None, num_inst=None, traceflags=0, insn_bytes=None, strict_block_end=None, collect_data_refs=False, cross_insn_opt=True, load_from_ro_regions=False, const_prop=False, initial_regs=None, skip_stmts=False)
Overloads:

  • self, addr (int), size, max_size, byte_string, thumb, backup_state, extra_stop_points, opt_level, num_inst, traceflags, insn_bytes, strict_block_end, collect_data_refs, cross_insn_opt, load_from_ro_regions, const_prop, initial_regs, skip_stmts → Block

  • self, addr (SootAddressDescriptor), size, max_size, byte_string, thumb, backup_state, extra_stop_points, opt_level, num_inst, traceflags, insn_bytes, strict_block_end, collect_data_refs, load_from_ro_regions, const_prop, cross_insn_opt, skip_stmts → SootBlock

fresh_block(addr, size, backup_state=None)