angr — Analysis and Coordination

Project

angr.project.fake_project_unpickler(name)
angr.project.load_shellcode(shellcode, arch, start_offset=0, load_address=0)

Load a new project based on a string of raw bytecode.

Parameters:
  • shellcode – The data to load
  • arch – The name of the arch to use, or an archinfo class
  • start_offset – The offset into the data to start analysis (default 0)
  • load_address – The address to place the data in memory (default 0)
class angr.project.Project(thing, default_analysis_mode=None, ignore_functions=None, use_sim_procedures=True, exclude_sim_procedures_func=None, exclude_sim_procedures_list=(), arch=None, simos=None, load_options=None, translation_cache=True, support_selfmodifying_code=False, store_function=None, load_function=None, analyses_preset=None, engines_preset=None, **kwargs)

Bases: object

This is the main class of the angr module. It is meant to contain a set of binaries and the relationships between them, and perform analyses on them.

Parameters:thing – The path to the main executable object to analyze, or a CLE Loader object.

The following parameters are optional.

Parameters:
  • default_analysis_mode – The mode of analysis to use by default. Defaults to ‘symbolic’.
  • ignore_functions – A list of function names that, when imported from shared libraries, should never be stepped into in analysis (calls will return an unconstrained value).
  • use_sim_procedures – Whether to replace resolved dependencies for which simprocedures are available with said simprocedures.
  • exclude_sim_procedures_func – A function that, when passed a function name, returns whether or not to wrap it with a simprocedure.
  • exclude_sim_procedures_list – A list of functions to not wrap with simprocedures.
  • arch – The target architecture (auto-detected otherwise).
  • simos – a SimOS class to use for this project.
  • translation_cache (bool) – If True, cache translated basic blocks rather than re-translating them.
  • support_selfmodifying_code (bool) – Whether we aggressively support self-modifying code. When enabled, emulation will try to read code from the current state instead of the original memory, regardless of the current memory protections.
  • store_function – A function that defines how the Project should be stored. Default to pickling.
  • load_function – A function that defines how the Project should be loaded. Default to unpickling.
  • analyses_preset (angr.misc.PluginPreset) – The plugin preset for the analyses provider (i.e. Analyses instance).
  • engines_preset (angr.misc.PluginPreset) – The plugin preset for the engines provider (i.e. EngineHub instance).

Any additional keyword arguments passed will be passed onto cle.Loader.

Variables:
  • analyses – The available analyses.
  • entry – The program entrypoint.
  • factory – Provides access to important analysis elements such as path groups and symbolic execution results.
  • filename – The filename of the executable.
  • loader – The program loader.
  • storage – Dictionary of things that should be loaded/stored with the Project.
hook(addr, hook=None, length=0, kwargs=None, replace=False)

Hook a section of code with a custom function. This is used internally to provide symbolic summaries of library functions, and can be used to instrument execution or to modify control flow.

When hook is not specified, it returns a function decorator that allows easy hooking. Usage:

# Assuming proj is an instance of angr.Project, we will add a custom hook at the entry
# point of the project.
@proj.hook(proj.entry)
def my_hook(state):
    print("Welcome to execution!")
Parameters:
  • addr – The address to hook.
  • hook – A angr.project.Hook describing a procedure to run at the given address. You may also pass in a SimProcedure class or a function directly and it will be wrapped in a Hook object for you.
  • length – If you provide a function for the hook, this is the number of bytes that will be skipped by executing the hook by default.
  • kwargs – If you provide a SimProcedure for the hook, these are the keyword arguments that will be passed to the procedure’s run method eventually.
  • replace – Control the behavior on finding that the address is already hooked. If true, silently replace the hook. If false (default), warn and do not replace the hook. If none, warn and replace the hook.
is_hooked(addr)

Returns True if addr is hooked.

Parameters:addr – An address.
Returns:True if addr is hooked, False otherwise.
hooked_by(addr)

Returns the current hook for addr.

Parameters:addr – An address.
Returns:None if the address is not hooked.
unhook(addr)

Remove a hook.

Parameters:addr – The address of the hook.
hook_symbol(symbol_name, simproc, kwargs=None, replace=None)

Resolve a dependency in a binary. Looks up the address of the given symbol, and then hooks that address. If the symbol was not available in the loaded libraries, this address may be provided by the CLE externs object.

Additionally, if instead of a symbol name you provide an address, some secret functionality will kick in and you will probably just hook that address, UNLESS you’re on powerpc64 ABIv1 or some yet-unknown scary ABI that has its function pointers point to something other than the actual functions, in which case it’ll do the right thing.

Parameters:
  • symbol_name – The name of the dependency to resolve.
  • simproc – The SimProcedure instance (or function) with which to hook the symbol
  • kwargs – If you provide a SimProcedure for the hook, these are the keyword arguments that will be passed to the procedure’s run method eventually.
  • replace – Control the behavior on finding that the address is already hooked. If true, silently replace the hook. If false, warn and do not replace the hook. If none (default), warn and replace the hook.
Returns:

The address of the new symbol.

Return type:

int

is_symbol_hooked(symbol_name)

Check if a symbol is already hooked.

Parameters:symbol_name (str) – Name of the symbol.
Returns:True if the symbol can be resolved and is hooked, False otherwise.
Return type:bool
unhook_symbol(symbol_name)

Remove the hook on a symbol. This function will fail if the symbol is provided by the extern object, as that would result in a state where analysis would be unable to cope with a call to this symbol.

execute(*args, **kwargs)

This function is a symbolic execution helper in the simple style supported by triton and manticore. It designed to be run after setting up hooks (see Project.hook), in which the symbolic state can be checked.

This function can be run in three different ways:

  • When run with no parameters, this function begins symbolic execution from the entrypoint.
  • It can also be run with a “state” parameter specifying a SimState to begin symbolic execution from.
  • Finally, it can accept any arbitrary keyword arguments, which are all passed to project.factory.full_init_state.

If symbolic execution finishes, this function returns the resulting simulation manager.

terminate_execution()

Terminates a symbolic execution that was started with Project.execute().

class angr.factory.AngrObjectFactory(project)

Bases: object

This factory provides access to important analysis elements.

default_engine
procedure_engine
snippet(addr, jumpkind=None, **block_opts)
successors(*args, **kwargs)

Perform execution using any applicable engine. Enumerate the current engines and use the first one that works. Return a SimSuccessors object classifying the results of the run.

Parameters:
  • state – The state to analyze
  • 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.

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 arguments to the program. 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 fully initialized state.

Return type:

SimState

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.

The following parametrs are optional.

Parameters:
  • 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 sequencial allocations happen at increasing addresses.

simulation_manager(thing=None, **kwargs)

Constructs a new simulation manager.

Parameters:
  • thing – Optional - 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:

angr.sim_manager.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, concrete_only=False, perform_merge=True, base_state=None, toc=None, cc=None)

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

Parameters:
  • addr – The address of the function to use
  • 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
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(args=None, ret_val=None, sp_delta=None, func_ty=None)

Return a SimCC (calling convention) parametrized for this project and, optionally, a given function.

Parameters:
  • args – A list of argument storage locations, as SimFunctionArguments.
  • ret_val – The return value storage location, as a SimFunctionArgument.
  • sp_delta – Does this even matter??
  • func_ty – The prototype for the given function, as a SimType or a C-style function declaration that can be parsed into a SimTypeFunction instance.

Example func_ty strings: >>> “int func(char*, int)” >>> “int f(int, int, int*);” Function names are ignored.

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.

cc_from_arg_kinds(fp_args, ret_fp=None, sizes=None, sp_delta=None, func_ty=None)

Get a SimCC (calling convention) that will extract floating-point/integral args correctly.

Parameters:
  • arch – The Archinfo arch for this CC
  • fp_args – A list, with one entry for each argument the function can take. True if the argument is fp, false if it is integral.
  • ret_fp – True if the return value for the function is fp.
  • sizes – Optional: A list, with one entry for each argument the function can take. Each entry is the size of the corresponding argument in bytes.
  • sp_delta – The amount the stack pointer changes over the course of this function - CURRENTLY UNUSED
  • func_ty – A SimType for the function itself or a C-style function declaration that can be parsed into a SimTypeFunction instance.

Example func_ty strings: >>> “int func(char*, int)” >>> “int f(int, int, int*);” Function names are ignored.

block(addr, size=None, max_size=None, byte_string=None, vex=None, thumb=False, backup_state=None, opt_level=None, num_inst=None, traceflags=0, insn_bytes=None, insn_text=None, strict_block_end=None, collect_data_refs=False)
fresh_block(addr, size, backup_state=None)
class angr.block.Block(addr, project=None, arch=None, size=None, byte_string=None, vex=None, thumb=False, backup_state=None, opt_level=None, num_inst=None, traceflags=0, strict_block_end=None, collect_data_refs=False)

Bases: object

BLOCK_MAX_SIZE = 4096
arch
thumb
addr
size
pp()
vex
vex_nostmt
capstone
codenode
bytes
instructions
instruction_addrs
class angr.block.CapstoneBlock(addr, insns, thumb, arch)

Bases: object

Deep copy of the capstone blocks, which have serious issues with having extended lifespans outside of capstone itself

addr
insns
thumb
arch
pp()
class angr.block.CapstoneInsn(capstone_insn)

Bases: object

Plugin Ecosystem

class angr.misc.plugins.PluginHub

Bases: object

A plugin hub is an object which contains many plugins, as well as the notion of a “preset”, or a backer that can provide default implementations of plugins which cater to a certain circumstance.

Objects in angr like the SimState, the Analyses hub, the SimEngine selector, etc all use this model to unify their mechanisms for automatically collecting and selecting components to use. If you’re familiar with design patterns this is a configurable Strategy Pattern.

Each PluginHub subclass should have a corresponding Plugin subclass, and perhaps a PluginPreset subclass if it wants its presets to be able to specify anything more interesting than a list of defaults.

classmethod register_default(name, plugin_cls, preset='default')
classmethod register_preset(name, preset)

Register a preset instance with the class of the hub it corresponds to. This allows individual plugin objects to automatically register themselves with a preset by using a classmethod of their own with only the name of the preset to register with.

plugin_preset

Get the current active plugin preset

has_plugin_preset

Check whether or not there is a plugin preset in use on this hub right now

use_plugin_preset(preset)

Apply a preset to the hub. If there was a previously active preset, discard it.

Preset can be either the string name of a preset or a PluginPreset instance.

discard_plugin_preset()

Discard the current active preset. Will release any active plugins that could have come from the old preset.

get_plugin(name)

Get the plugin named name. If no such plugin is currently active, try to activate a new one using the current preset.

has_plugin(name)

Return whether or not a plugin with the name name is curently active.

register_plugin(name, plugin)

Add a new plugin plugin with name name to the active plugins.

release_plugin(name)

Deactivate and remove the plugin with name name.

class angr.misc.plugins.PluginPreset

Bases: object

A plugin preset object contains a mapping from name to a plugin class. A preset can be active on a hub, which will cause it to handle requests for plugins which are not already present on the hub.

Unlike Plugins and PluginHubs, instances of PluginPresets are defined on the module level for individual presets. You should register the preset instance with a hub to allow plugins to easily add themselves to the preset without an explicit reference to the preset itself.

activate(hub)

This method is called when the preset becomes active on a hub.

deactivate(hub)

This method is called when the preset is discarded from the hub.

add_default_plugin(name, plugin_cls)

Add a plugin to the preset.

list_default_plugins()

Return a list of the names of available default plugins.

request_plugin(name)

Return the plugin class which is registered under the name name, or raise NoPlugin if the name isn’t available.

copy()

Return a copy of self.

class angr.misc.plugins.PluginVendor

Bases: angr.misc.plugins.PluginHub

A specialized hub which serves only as a plugin vendor, never having any “active” plugins. It will directly return the plugins provided by the preset instead of instanciating them.

release_plugin(name)
register_plugin(name, plugin)
class angr.misc.plugins.VendorPreset

Bases: angr.misc.plugins.PluginPreset

A specialized preset class for use with the PluginVendor.

Program State

angr.sim_state.arch_overrideable(f)
class angr.sim_state.SimState(project=None, arch=None, plugins=None, memory_backer=None, permissions_backer=None, mode=None, options=None, add_options=None, remove_options=None, special_memory_filler=None, os_name=None, plugin_preset='default', **kwargs)

Bases: angr.misc.plugins.PluginHub, ana.storable.Storable

The SimState represents the state of a program, including its memory, registers, and so forth.

Parameters:
  • project (angr.Project) –
  • arch (archinfo.Arch) –
Variables:
  • regs – A convenient view of the state’s registers, where each register is a property
  • mem – A convenient view of the state’s memory, a angr.state_plugins.view.SimMemView
  • registers – The state’s register file as a flat memory region
  • memory – The state’s memory as a flat memory region
  • solver – The symbolic solver and variable manager for this state
  • inspect – The breakpoint manager, a angr.state_plugins.inspect.SimInspector
  • log – Information about the state’s history
  • scratch – Information about the current execution step
  • posix – MISNOMER: information about the operating system or environment model
  • fs – The current state of the simulated filesystem
  • libc – Information about the standard library we are emulating
  • cgc – Information about the cgc environment
  • uc_manager – Control of under-constrained symbolic execution
  • unicorn (str) – Control of the Unicorn Engine
plugins
se

Deprecated alias for solver

ip

Get the instruction pointer expression, trigger SimInspect breakpoints, and generate SimActions. Use _ip to not trigger breakpoints or generate actions.

Returns:an expression
addr

Get the concrete address of the instruction pointer, without triggering SimInspect breakpoints or generating SimActions. An integer is returned, or an exception is raised if the instruction pointer is symbolic.

Returns:an int
options
register_plugin(name, plugin, inhibit_init=False)
simplify(*args)

Simplify this state’s constraints.

add_constraints(*args, **kwargs)

Add some constraints to the state.

You may pass in any number of symbolic booleans as variadic positional arguments.

satisfiable(**kwargs)

Whether the state’s constraints are satisfiable

downsize()

Clean up after the solver engine. Calling this when a state no longer needs to be solved on will reduce memory usage.

step(**kwargs)

Perform a step of symbolic execution using this state. Any arguments to AngrObjectFactory.successors can be passed to this.

Returns:A SimSuccessors object categorizing the results of the step.
block(*args, **kwargs)

Represent the basic block at this state’s instruction pointer. Any arguments to AngrObjectFactory.block can ba passed to this.

Returns:A Block object describing the basic block of code at this point.
copy()

Returns a copy of the state.

merge(*others, **kwargs)

Merges this state with the other states. Returns the merging result, merged state, and the merge flag.

Parameters:
  • states – the states to merge
  • merge_conditions – a tuple of the conditions under which each state holds
  • common_ancestor – a state that represents the common history between the states being merged. Usually it is only available when EFFICIENT_STATE_MERGING is enabled, otherwise weak-refed states might be dropped from state history instances.
  • plugin_whitelist – a list of plugin names that will be merged. If this option is given and is not None, any plugin that is not inside this list will not be merged, and will be created as a fresh instance in the new state.
  • common_ancestor_history – a SimStateHistory instance that represents the common history between the states being merged. This is to allow optimal state merging when EFFICIENT_STATE_MERGING is disabled.
Returns:

(merged state, merge flag, a bool indicating if any merging occured)

widen(*others)

Perform a widening between self and other states :param others: :return:

reg_concrete(*args, **kwargs)

Returns the contents of a register but, if that register is symbolic, raises a SimValueError.

mem_concrete(*args, **kwargs)

Returns the contents of a memory but, if the contents are symbolic, raises a SimValueError.

stack_push(thing)

Push ‘thing’ to the stack, writing the thing to memory and adjusting the stack pointer.

stack_pop()

Pops from the stack and returns the popped thing. The length will be the architecture word size.

stack_read(offset, length, bp=False)

Reads length bytes, at an offset into the stack.

Parameters:
  • offset – The offset from the stack pointer.
  • length – The number of bytes to read.
  • bp – If True, offset from the BP instead of the SP. Default: False.
make_concrete_int(expr)
prepare_callsite(retval, args, cc='wtf')
dbg_print_stack(depth=None, sp=None)

Only used for debugging purposes. Return the current stack info in formatted string. If depth is None, the current stack frame (from sp to bp) will be printed out.

set_mode(mode)
thumb
with_condition
class angr.sim_state_options.StateOption(name, types, default='_NO_DEFAULT_VALUE', description=None)

Bases: object

Describes a state option.

name
types
default
description
has_default_value
one_type()
class angr.sim_state_options.SimStateOptions(thing)

Bases: object

A per-state manager of state options. An option can be either a key-valued entry or a Boolean switch (which can be seen as a key-valued entry whose value can only be either True or False).

Parameters:thing – Either a set of Boolean switches to enable, or an existing SimStateOptions instance.
OPTIONS = {'ABSTRACT_MEMORY': <O ABSTRACT_MEMORY[bool]>, 'ABSTRACT_SOLVER': <O ABSTRACT_SOLVER[bool]>, 'ACTION_DEPS': <O ACTION_DEPS[bool]>, 'ALL_FILES_EXIST': <O ALL_FILES_EXIST[bool]>, 'APPROXIMATE_GUARDS': <O APPROXIMATE_GUARDS[bool]>, 'APPROXIMATE_MEMORY_INDICES': <O APPROXIMATE_MEMORY_INDICES[bool]>, 'APPROXIMATE_MEMORY_SIZES': <O APPROXIMATE_MEMORY_SIZES[bool]>, 'APPROXIMATE_SATISFIABILITY': <O APPROXIMATE_SATISFIABILITY[bool]>, 'AST_DEPS': <O AST_DEPS[bool]>, 'AUTO_REFS': <O AUTO_REFS[bool]>, 'AVOID_MULTIVALUED_READS': <O AVOID_MULTIVALUED_READS[bool]>, 'AVOID_MULTIVALUED_WRITES': <O AVOID_MULTIVALUED_WRITES[bool]>, 'BEST_EFFORT_MEMORY_STORING': <O BEST_EFFORT_MEMORY_STORING[bool]>, 'BLOCK_SCOPE_CONSTRAINTS': <O BLOCK_SCOPE_CONSTRAINTS[bool]>, 'BREAK_SIRSB_END': <O BREAK_SIRSB_END[bool]>, 'BREAK_SIRSB_START': <O BREAK_SIRSB_START[bool]>, 'BREAK_SIRSTMT_END': <O BREAK_SIRSTMT_END[bool]>, 'BREAK_SIRSTMT_START': <O BREAK_SIRSTMT_START[bool]>, 'BYPASS_ERRORED_IRCCALL': <O BYPASS_ERRORED_IRCCALL[bool]>, 'BYPASS_ERRORED_IROP': <O BYPASS_ERRORED_IROP[bool]>, 'BYPASS_UNSUPPORTED_IRCCALL': <O BYPASS_UNSUPPORTED_IRCCALL[bool]>, 'BYPASS_UNSUPPORTED_IRDIRTY': <O BYPASS_UNSUPPORTED_IRDIRTY[bool]>, 'BYPASS_UNSUPPORTED_IREXPR': <O BYPASS_UNSUPPORTED_IREXPR[bool]>, 'BYPASS_UNSUPPORTED_IROP': <O BYPASS_UNSUPPORTED_IROP[bool]>, 'BYPASS_UNSUPPORTED_IRSTMT': <O BYPASS_UNSUPPORTED_IRSTMT[bool]>, 'BYPASS_UNSUPPORTED_SYSCALL': <O BYPASS_UNSUPPORTED_SYSCALL[bool]>, 'BYPASS_VERITESTING_EXCEPTIONS': <O BYPASS_VERITESTING_EXCEPTIONS[bool]>, 'CACHELESS_SOLVER': <O CACHELESS_SOLVER[bool]>, 'CALLLESS': <O CALLLESS[bool]>, 'CGC_ENFORCE_FD': <O CGC_ENFORCE_FD[bool]>, 'CGC_NON_BLOCKING_FDS': <O CGC_NON_BLOCKING_FDS[bool]>, 'CGC_NO_SYMBOLIC_RECEIVE_LENGTH': <O CGC_NO_SYMBOLIC_RECEIVE_LENGTH[bool]>, 'COMPOSITE_SOLVER': <O COMPOSITE_SOLVER[bool]>, 'CONCRETIZE': <O CONCRETIZE[bool]>, 'CONCRETIZE_SYMBOLIC_FILE_READ_SIZES': <O CONCRETIZE_SYMBOLIC_FILE_READ_SIZES[bool]>, 'CONCRETIZE_SYMBOLIC_WRITE_SIZES': <O CONCRETIZE_SYMBOLIC_WRITE_SIZES[bool]>, 'CONSERVATIVE_READ_STRATEGY': <O CONSERVATIVE_READ_STRATEGY[bool]>, 'CONSERVATIVE_WRITE_STRATEGY': <O CONSERVATIVE_WRITE_STRATEGY[bool]>, 'CONSTRAINT_TRACKING_IN_SOLVER': <O CONSTRAINT_TRACKING_IN_SOLVER[bool]>, 'COW_STATES': <O COW_STATES[bool]>, 'DOWNSIZE_Z3': <O DOWNSIZE_Z3[bool]>, 'DO_CCALLS': <O DO_CCALLS[bool]>, 'DO_GETS': <O DO_GETS[bool]>, 'DO_LOADS': <O DO_LOADS[bool]>, 'DO_OPS': <O DO_OPS[bool]>, 'DO_PUTS': <O DO_PUTS[bool]>, 'DO_RET_EMULATION': <O DO_RET_EMULATION[bool]>, 'DO_STORES': <O DO_STORES[bool]>, 'EFFICIENT_STATE_MERGING': <O EFFICIENT_STATE_MERGING[bool]>, 'ENABLE_NX': <O ENABLE_NX[bool]>, 'EXCEPTION_HANDLING': <O EXCEPTION_HANDLING[bool]>, 'EXTENDED_IROP_SUPPORT': <O EXTENDED_IROP_SUPPORT[bool]>, 'FAST_MEMORY': <O FAST_MEMORY[bool]>, 'FAST_REGISTERS': <O FAST_REGISTERS[bool]>, 'FILES_HAVE_EOF': <O FILES_HAVE_EOF[bool]>, 'INITIALIZE_ZERO_REGISTERS': <O INITIALIZE_ZERO_REGISTERS[bool]>, 'INSTRUCTION_SCOPE_CONSTRAINTS': <O INSTRUCTION_SCOPE_CONSTRAINTS[bool]>, 'KEEP_IP_SYMBOLIC': <O KEEP_IP_SYMBOLIC[bool]>, 'KEEP_MEMORY_READS_DISCRETE': <O KEEP_MEMORY_READS_DISCRETE[bool]>, 'LAZY_SOLVES': <O LAZY_SOLVES[bool]>, 'MEMORY_SYMBOLIC_BYTES_MAP': <O MEMORY_SYMBOLIC_BYTES_MAP[bool]>, 'NO_SYMBOLIC_JUMP_RESOLUTION': <O NO_SYMBOLIC_JUMP_RESOLUTION[bool]>, 'NO_SYMBOLIC_SYSCALL_RESOLUTION': <O NO_SYMBOLIC_SYSCALL_RESOLUTION[bool]>, 'OPTIMIZE_IR': <O OPTIMIZE_IR[bool]>, 'PRODUCE_ZERODIV_SUCCESSORS': <O PRODUCE_ZERODIV_SUCCESSORS[bool]>, 'REGION_MAPPING': <O REGION_MAPPING[bool]>, 'REPLACEMENT_SOLVER': <O REPLACEMENT_SOLVER[bool]>, 'REVERSE_MEMORY_HASH_MAP': <O REVERSE_MEMORY_HASH_MAP[bool]>, 'REVERSE_MEMORY_NAME_MAP': <O REVERSE_MEMORY_NAME_MAP[bool]>, 'SHORT_READS': <O SHORT_READS[bool]>, 'SIMPLIFY_CONSTRAINTS': <O SIMPLIFY_CONSTRAINTS[bool]>, 'SIMPLIFY_EXIT_GUARD': <O SIMPLIFY_EXIT_GUARD[bool]>, 'SIMPLIFY_EXIT_STATE': <O SIMPLIFY_EXIT_STATE[bool]>, 'SIMPLIFY_EXIT_TARGET': <O SIMPLIFY_EXIT_TARGET[bool]>, 'SIMPLIFY_EXPRS': <O SIMPLIFY_EXPRS[bool]>, 'SIMPLIFY_MEMORY_READS': <O SIMPLIFY_MEMORY_READS[bool]>, 'SIMPLIFY_MEMORY_WRITES': <O SIMPLIFY_MEMORY_WRITES[bool]>, 'SIMPLIFY_REGISTER_READS': <O SIMPLIFY_REGISTER_READS[bool]>, 'SIMPLIFY_REGISTER_WRITES': <O SIMPLIFY_REGISTER_WRITES[bool]>, 'SIMPLIFY_RETS': <O SIMPLIFY_RETS[bool]>, 'SPECIAL_MEMORY_FILL': <O SPECIAL_MEMORY_FILL[bool]>, 'STRICT_PAGE_ACCESS': <O STRICT_PAGE_ACCESS[bool]>, 'SUPER_FASTPATH': <O SUPER_FASTPATH[bool]>, 'SUPPORT_FLOATING_POINT': <O SUPPORT_FLOATING_POINT[bool]>, 'SYMBOLIC': <O SYMBOLIC[bool]>, 'SYMBOLIC_INITIAL_VALUES': <O SYMBOLIC_INITIAL_VALUES[bool]>, 'SYMBOLIC_TEMPS': <O SYMBOLIC_TEMPS[bool]>, 'SYMBOLIC_WRITE_ADDRESSES': <O SYMBOLIC_WRITE_ADDRESSES[bool]>, 'TRACK_ACTION_HISTORY': <O TRACK_ACTION_HISTORY[bool]>, 'TRACK_CONSTRAINTS': <O TRACK_CONSTRAINTS[bool]>, 'TRACK_CONSTRAINT_ACTIONS': <O TRACK_CONSTRAINT_ACTIONS[bool]>, 'TRACK_JMP_ACTIONS': <O TRACK_JMP_ACTIONS[bool]>, 'TRACK_MEMORY_ACTIONS': <O TRACK_MEMORY_ACTIONS[bool]>, 'TRACK_MEMORY_MAPPING': <O TRACK_MEMORY_MAPPING[bool]>, 'TRACK_OP_ACTIONS': <O TRACK_OP_ACTIONS[bool]>, 'TRACK_REGISTER_ACTIONS': <O TRACK_REGISTER_ACTIONS[bool]>, 'TRACK_SOLVER_VARIABLES': <O TRACK_SOLVER_VARIABLES[bool]>, 'TRACK_TMP_ACTIONS': <O TRACK_TMP_ACTIONS[bool]>, 'TRUE_RET_EMULATION_GUARD': <O TRUE_RET_EMULATION_GUARD[bool]>, 'UNDER_CONSTRAINED_SYMEXEC': <O UNDER_CONSTRAINED_SYMEXEC[bool]>, 'UNICORN': <O UNICORN[bool]>, 'UNICORN_AGGRESSIVE_CONCRETIZATION': <O UNICORN_AGGRESSIVE_CONCRETIZATION[bool]>, 'UNICORN_HANDLE_TRANSMIT_SYSCALL': <O UNICORN_HANDLE_TRANSMIT_SYSCALL[bool]>, 'UNICORN_SYM_REGS_SUPPORT': <O UNICORN_SYM_REGS_SUPPORT[bool]>, 'UNICORN_THRESHOLD_CONCRETIZATION': <O UNICORN_THRESHOLD_CONCRETIZATION[bool]>, 'UNICORN_TRACK_BBL_ADDRS': <O UNICORN_TRACK_BBL_ADDRS[bool]>, 'UNICORN_TRACK_STACK_POINTERS': <O UNICORN_TRACK_STACK_POINTERS[bool]>, 'UNICORN_ZEROPAGE_GUARD': <O UNICORN_ZEROPAGE_GUARD[bool]>, 'UNINITIALIZED_ACCESS_AWARENESS': <O UNINITIALIZED_ACCESS_AWARENESS[bool]>, 'UNSUPPORTED_BYPASS_ZERO_DEFAULT': <O UNSUPPORTED_BYPASS_ZERO_DEFAULT[bool]>, 'USE_SIMPLIFIED_CCALLS': <O USE_SIMPLIFIED_CCALLS[bool]>, 'USE_SYSTEM_TIMES': <O USE_SYSTEM_TIMES[bool]>, 'VALIDATE_APPROXIMATIONS': <O VALIDATE_APPROXIMATIONS[bool]>, 'ZERO_FILL_UNCONSTRAINED_MEMORY': <O ZERO_FILL_UNCONSTRAINED_MEMORY[bool]>, 'jumptable_symbolic_ip_max_targets': <O jumptable_symbolic_ip_max_targets[int]: The maximum number of concrete addresses a symbolic instruction pointer can be concretized to if it is part of a jump table.>, 'symbolic_ip_max_targets': <O symbolic_ip_max_targets[int]: The maximum number of concrete addresses a symbolic instruction pointer can be concretized to.>}
add(boolean_switch)

[COMPATIBILITY] Enable a Boolean switch.

Parameters:boolean_switch (str) – Name of the Boolean switch.
Returns:None
update(boolean_switches)

[COMPATIBILITY] In order to be compatible with the old interface, you can enable a collection of Boolean switches at the same time by doing the following:

>>> state.options.update({sim_options.SYMBOLIC, sim_options.ABSTRACT_MEMORY})

or

>>> state.options.update(sim_options.unicorn)
Parameters:boolean_switches (set) – A collection of Boolean switches to enable.
Returns:None
remove(name)

Drop a state option if it exists, or raise a KeyError if the state option is not set.

[COMPATIBILITY] Remove a Boolean switch.

Parameters:name (str) – Name of the state option.
Returns:NNone
discard(name)

Drop a state option if it exists, or silently return if the state option is not set.

[COMPATIBILITY] Disable a Boolean switch.

Parameters:name (str) – Name of the Boolean switch.
Returns:None
difference(boolean_switches)

[COMPATIBILITY] Make a copy of the current instance, and then discard all options that are in boolean_switches.

Parameters:boolean_switches (set) – A collection of Boolean switches to disable.
Returns:A new SimStateOptions instance.
copy()

Get a copy of the current SimStateOptions instance.

Returns:A new SimStateOptions instance.
Return type:SimStateOptions
tally(exclude_false=True, description=False)

Return a string representation of all state options.

Parameters:
  • exclude_false (bool) – Whether to exclude Boolean switches that are disabled.
  • description (bool) – Whether to display the description of each option.
Returns:

A string representation.

Return type:

str

classmethod register_option(name, types, default=None, description=None)

Register a state option.

Parameters:
  • name (str) – Name of the state option.
  • types – A collection of allowed types of this state option.
  • default – The default value of this state option.
  • description (str) – The description of this state option.
Returns:

None

classmethod register_bool_option(name, description=None)

Register a Boolean switch as state option. This is equivalent to cls.register_option(name, set([bool]), description=description)

Parameters:
  • name (str) – Name of the state option.
  • description (str) – The description of this state option.
Returns:

None

class angr.state_plugins.plugin.SimStatePlugin

Bases: object

This is a base class for SimState plugins. A SimState plugin will be copied along with the state when the state is branched. They are intended to be used for things such as tracking open files, tracking heap details, and providing storage and persistence for SimProcedures.

STRONGREF_STATE = False
set_state(state)

Sets a new state (for example, if the state has been branched)

set_strongref_state(state)
copy(_memo)

Should return a copy of the plugin without any state attached. Should check the memo first, and add itself to memo if it ends up making a new copy.

In order to simplify using the memo, you should annotate implementations of this function with SimStatePlugin.memo

Parameters:memo – A dictionary mapping object identifiers (id(obj)) to their copied instance. Use this to avoid infinite recursion and diverged copies.
static memo(f)

A decorator function you should apply to copy

merge(_others, _merge_conditions, _common_ancestor=None)

Should merge the state plugin with the provided others. This will be called by state.merge() after copying the target state, so this should mutate the current instance to merge with the others.

Note that when multiple instances of a single plugin object (for example, a file) are referenced in the state, it is important that merge only ever be called once. This should be solved by designating one of the plugin’s referees as the “real owner”, who should be the one to actually merge it. This technique doesn’t work to resolve the similar issue that arises during copying because merging doesn’t produce a new reference to insert.

There will be n others and n+1 merge conditions, since the first condition corresponds to self. To match elements up to conditions, say zip([self] + others, merge_conditions)

When implementing this, make sure that you “deepen” both others and common_ancestor before calling sub-elements’ merge methods, e.g. self.foo.merge([o.foo for o in others], merge_conditions, common_ancestor=common_ancestor.foo if common_ancestor is not None else None).

During static analysis, merge_conditions can be None, in which case you should use state.solver.union(values). TODO: fish please make this less bullshit

There is a utility state.solver.ite_cases which will help with constructing arbitrarily large merged ASTs. Use it like self.bar = self.state.solver.ite_cases(zip(conditions[1:], [o.bar for o in others]), self.bar)

Parameters:
  • others – the other state plugins to merge with
  • merge_conditions – a symbolic condition for each of the plugins
  • common_ancestor – a common ancestor of this plugin and the others being merged
Returns:

True if the state plugins are actually merged.

Return type:

bool

widen(_others)

The widening operation for plugins. Widening is a special kind of merging that produces a more general state from several more specific states. It is used only during intensive static analysis. The same behavior regarding copying and mutation from merge should be followed.

Parameters:others – the other state plugin
Returns:True if the state plugin is actually widened.
Return type:bool
classmethod register_default(name, xtr=None)
init_state()

Use this function to perform any initialization on the state at plugin-add time

class angr.state_plugins.inspect.BP(when='before', enabled=None, condition=None, action=None, **kwargs)

Bases: object

A breakpoint.

check(state, when)

Checks state state to see if the breakpoint should fire.

Parameters:
  • state – The state.
  • when – Whether the check is happening before or after the event.
Returns:

A boolean representing whether the checkpoint should fire.

fire(state)

Trigger the breakpoint.

Parameters:state – The state.
class angr.state_plugins.inspect.SimInspector

Bases: angr.state_plugins.plugin.SimStatePlugin

The breakpoint interface, used to instrument execution. For usage information, look here: https://docs.angr.io/docs/simuvex.html#breakpoints

BP_AFTER = 'after'
BP_BEFORE = 'before'
BP_BOTH = 'both'
action(event_type, when, **kwargs)

Called from within SimuVEX when events happens. This function checks all breakpoints registered for that event and fires the ones whose conditions match.

make_breakpoint(event_type, *args, **kwargs)

Creates and adds a breakpoint which would trigger on event_type. Additional arguments are passed to the BP constructor.

Returns:The created breakpoint, so that it can be removed later.
b(event_type, *args, **kwargs)

Creates and adds a breakpoint which would trigger on event_type. Additional arguments are passed to the BP constructor.

Returns:The created breakpoint, so that it can be removed later.
add_breakpoint(event_type, bp)

Adds a breakpoint which would trigger on event_type.

Parameters:
  • event_type – The event type to trigger on
  • bp – The breakpoint
Returns:

The created breakpoint.

remove_breakpoint(event_type, bp=None, filter_func=None)

Removes a breakpoint.

Parameters:
  • bp – The breakpoint to remove.
  • filter_func – A filter function to specify whether each breakpoint should be removed or not.
copy(memo=None, **kwargs)
downsize()

Remove previously stored attributes from this plugin instance to save memory. This method is supposed to be called by breakpoint implementors. A typical workflow looks like the following :

>>> # Add `attr0` and `attr1` to `self.state.inspect`
>>> self.state.inspect(xxxxxx, attr0=yyyy, attr1=zzzz)
>>> # Get new attributes out of SimInspect in case they are modified by the user
>>> new_attr0 = self.state._inspect.attr0
>>> new_attr1 = self.state._inspect.attr1
>>> # Remove them from SimInspect
>>> self.state._inspect.downsize()
merge(others, merge_conditions, common_ancestor=None)
widen(others)
class angr.state_plugins.libc.SimStateLibc

Bases: angr.state_plugins.plugin.SimStatePlugin

This state plugin keeps track of various libc stuff:

LOCALE_ARRAY = [b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x02\x00', b'\x02\x00', b'\x02\x00', b'\x02\x00', b'\x02\x00', b'\x02\x00', b'\x02\x00', b'\x02\x00', b'\x02\x00', b'\x03 ', b'\x02 ', b'\x02 ', b'\x02 ', b'\x02 ', b'\x02\x00', b'\x02\x00', b'\x02\x00', b'\x02\x00', b'\x02\x00', b'\x02\x00', b'\x02\x00', b'\x02\x00', b'\x02\x00', b'\x02\x00', b'\x02\x00', b'\x02\x00', b'\x02\x00', b'\x02\x00', b'\x02\x00', b'\x02\x00', b'\x02\x00', b'\x02\x00', b'\x01`', b'\x04\xc0', b'\x04\xc0', b'\x04\xc0', b'\x04\xc0', b'\x04\xc0', b'\x04\xc0', b'\x04\xc0', b'\x04\xc0', b'\x04\xc0', b'\x04\xc0', b'\x04\xc0', b'\x04\xc0', b'\x04\xc0', b'\x04\xc0', b'\x04\xc0', b'\x08\xd8', b'\x08\xd8', b'\x08\xd8', b'\x08\xd8', b'\x08\xd8', b'\x08\xd8', b'\x08\xd8', b'\x08\xd8', b'\x08\xd8', b'\x08\xd8', b'\x04\xc0', b'\x04\xc0', b'\x04\xc0', b'\x04\xc0', b'\x04\xc0', b'\x04\xc0', b'\x04\xc0', b'\x08\xd5', b'\x08\xd5', b'\x08\xd5', b'\x08\xd5', b'\x08\xd5', b'\x08\xd5', b'\x08\xc5', b'\x08\xc5', b'\x08\xc5', b'\x08\xc5', b'\x08\xc5', b'\x08\xc5', b'\x08\xc5', b'\x08\xc5', b'\x08\xc5', b'\x08\xc5', b'\x08\xc5', b'\x08\xc5', b'\x08\xc5', b'\x08\xc5', b'\x08\xc5', b'\x08\xc5', b'\x08\xc5', b'\x08\xc5', b'\x08\xc5', b'\x08\xc5', b'\x04\xc0', b'\x04\xc0', b'\x04\xc0', b'\x04\xc0', b'\x04\xc0', b'\x04\xc0', b'\x08\xd6', b'\x08\xd6', b'\x08\xd6', b'\x08\xd6', b'\x08\xd6', b'\x08\xd6', b'\x08\xc6', b'\x08\xc6', b'\x08\xc6', b'\x08\xc6', b'\x08\xc6', b'\x08\xc6', b'\x08\xc6', b'\x08\xc6', b'\x08\xc6', b'\x08\xc6', b'\x08\xc6', b'\x08\xc6', b'\x08\xc6', b'\x08\xc6', b'\x08\xc6', b'\x08\xc6', b'\x08\xc6', b'\x08\xc6', b'\x08\xc6', b'\x08\xc6', b'\x04\xc0', b'\x04\xc0', b'\x04\xc0', b'\x04\xc0', b'\x02\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00', b'\x00\x00']
TOLOWER_LOC_ARRAY = [128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140, 141, 142, 143, 144, 145, 146, 147, 148, 149, 150, 151, 152, 153, 154, 155, 156, 157, 158, 159, 160, 161, 162, 163, 164, 165, 166, 167, 168, 169, 170, 171, 172, 173, 174, 175, 176, 177, 178, 179, 180, 181, 182, 183, 184, 185, 186, 187, 188, 189, 190, 191, 192, 193, 194, 195, 196, 197, 198, 199, 200, 201, 202, 203, 204, 205, 206, 207, 208, 209, 210, 211, 212, 213, 214, 215, 216, 217, 218, 219, 220, 221, 222, 223, 224, 225, 226, 227, 228, 229, 230, 231, 232, 233, 234, 235, 236, 237, 238, 239, 240, 241, 242, 243, 244, 245, 246, 247, 248, 249, 250, 251, 252, 253, 254, 4294967295, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 97, 98, 99, 100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140, 141, 142, 143, 144, 145, 146, 147, 148, 149, 150, 151, 152, 153, 154, 155, 156, 157, 158, 159, 160, 161, 162, 163, 164, 165, 166, 167, 168, 169, 170, 171, 172, 173, 174, 175, 176, 177, 178, 179, 180, 181, 182, 183, 184, 185, 186, 187, 188, 189, 190, 191, 192, 193, 194, 195, 196, 197, 198, 199, 200, 201, 202, 203, 204, 205, 206, 207, 208, 209, 210, 211, 212, 213, 214, 215, 216, 217, 218, 219, 220, 221, 222, 223, 224, 225, 226, 227, 228, 229, 230, 231, 232, 233, 234, 235, 236, 237, 238, 239, 240, 241, 242, 243, 244, 245, 246, 247, 248, 249, 250, 251, 252, 253, 254, 255]
TOUPPER_LOC_ARRAY = [128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140, 141, 142, 143, 144, 145, 146, 147, 148, 149, 150, 151, 152, 153, 154, 155, 156, 157, 158, 159, 160, 161, 162, 163, 164, 165, 166, 167, 168, 169, 170, 171, 172, 173, 174, 175, 176, 177, 178, 179, 180, 181, 182, 183, 184, 185, 186, 187, 188, 189, 190, 191, 192, 193, 194, 195, 196, 197, 198, 199, 200, 201, 202, 203, 204, 205, 206, 207, 208, 209, 210, 211, 212, 213, 214, 215, 216, 217, 218, 219, 220, 221, 222, 223, 224, 225, 226, 227, 228, 229, 230, 231, 232, 233, 234, 235, 236, 237, 238, 239, 240, 241, 242, 243, 244, 245, 246, 247, 248, 249, 250, 251, 252, 253, 254, 4294967295, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140, 141, 142, 143, 144, 145, 146, 147, 148, 149, 150, 151, 152, 153, 154, 155, 156, 157, 158, 159, 160, 161, 162, 163, 164, 165, 166, 167, 168, 169, 170, 171, 172, 173, 174, 175, 176, 177, 178, 179, 180, 181, 182, 183, 184, 185, 186, 187, 188, 189, 190, 191, 192, 193, 194, 195, 196, 197, 198, 199, 200, 201, 202, 203, 204, 205, 206, 207, 208, 209, 210, 211, 212, 213, 214, 215, 216, 217, 218, 219, 220, 221, 222, 223, 224, 225, 226, 227, 228, 229, 230, 231, 232, 233, 234, 235, 236, 237, 238, 239, 240, 241, 242, 243, 244, 245, 246, 247, 248, 249, 250, 251, 252, 253, 254, 255]
copy(memo=None, **kwargs)
merge(others, merge_conditions, common_ancestor=None)
widen(others)
init_state()
class angr.state_plugins.posix.Stat(st_dev, st_ino, st_nlink, st_mode, st_uid, st_gid, st_rdev, st_size, st_blksize, st_blocks, st_atime, st_atimensec, st_mtime, st_mtimensec, st_ctime, st_ctimensec)

Bases: tuple

Create new instance of Stat(st_dev, st_ino, st_nlink, st_mode, st_uid, st_gid, st_rdev, st_size, st_blksize, st_blocks, st_atime, st_atimensec, st_mtime, st_mtimensec, st_ctime, st_ctimensec)

st_atime

Alias for field number 10

st_atimensec

Alias for field number 11

st_blksize

Alias for field number 8

st_blocks

Alias for field number 9

st_ctime

Alias for field number 14

st_ctimensec

Alias for field number 15

st_dev

Alias for field number 0

st_gid

Alias for field number 5

st_ino

Alias for field number 1

st_mode

Alias for field number 3

st_mtime

Alias for field number 12

st_mtimensec

Alias for field number 13

Alias for field number 2

st_rdev

Alias for field number 6

st_size

Alias for field number 7

st_uid

Alias for field number 4

class angr.state_plugins.posix.PosixDevFS

Bases: angr.state_plugins.filesystem.SimMount

get(path)
insert(path, simfile)
delete(path)
merge(others, conditions, common_ancestor=None)
widen(others)
copy(_)
class angr.state_plugins.posix.SimSystemPosix(stdin=None, stdout=None, stderr=None, fd=None, sockets=None, socket_queue=None, argv=None, argc=None, environ=None, auxv=None, tls_modules=None, queued_syscall_returns=None, sigmask=None, pid=None, ppid=None, uid=None, gid=None, brk=None)

Bases: angr.state_plugins.plugin.SimStatePlugin

Data storage and interaction mechanisms for states with an environment conforming to posix. Available as state.posix.

SIG_BLOCK = 0
SIG_UNBLOCK = 1
SIG_SETMASK = 2
EPERM = 1
ENOENT = 2
ESRCH = 3
EINTR = 4
EIO = 5
ENXIO = 6
E2BIG = 7
ENOEXEC = 8
EBADF = 9
ECHILD = 10
EAGAIN = 11
ENOMEM = 12
EACCES = 13
EFAULT = 14
ENOTBLK = 15
EBUSY = 16
EEXIST = 17
EXDEV = 18
ENODEV = 19
ENOTDIR = 20
EISDIR = 21
EINVAL = 22
ENFILE = 23
EMFILE = 24
ENOTTY = 25
ETXTBSY = 26
EFBIG = 27
ENOSPC = 28
ESPIPE = 29
EROFS = 30
EPIPE = 32
EDOM = 33
ERANGE = 34
init_state()
set_brk(new_brk)
set_state(state)
open(name, flags, preferred_fd=None)

Open a symbolic file. Basically open(2).

Parameters:
  • name – Path of the symbolic file, as a string.
  • flags – File operation flags, a bitfield of constants from open(2), as an AST
  • preferred_fd – Assign this fd if it’s not already claimed.
Returns:

The file descriptor number allocated (maps through posix.get_fd to a SimFileDescriptor) or None if the open fails.

mode from open(2) is unsupported at present.

open_socket(ident)
get_fd(fd)

Looks up the SimFileDescriptor associated with the given number (an AST). If the number is concrete and does not map to anything, return None. If the number is symbolic, constrain it to an open fd and create a new file for it.

close(fd)

Closes the given file descriptor (an AST). Returns whether the operation succeeded (a concrete boolean)

fstat(fd)
sigmask(sigsetsize=None)

Gets the current sigmask. If it’s blank, a new one is created (of sigsetsize).

Parameters:sigsetsize – the size (in bytes of the sigmask set)
Returns:the sigmask
sigprocmask(how, new_mask, sigsetsize, valid_ptr=True)

Updates the signal mask.

Parameters:
  • how – the “how” argument of sigprocmask (see manpage)
  • new_mask – the mask modification to apply
  • sigsetsize – the size (in bytes of the sigmask set)
  • valid_ptr – is set if the new_mask was not NULL
copy(memo=None, **kwargs)
merge(others, merge_conditions, common_ancestor=None)
widen(_)
dump_file_by_path(path, **kwargs)

Returns the concrete content for a file by path.

Parameters:
  • path – file path as string
  • kwargs – passed to state.solver.eval
Returns:

file contents as string

dumps(fd, **kwargs)

Returns the concrete content for a file descriptor.

BACKWARD COMPATIBILITY: if you ask for file descriptors 0 1 or 2, it will return the data from stdin, stdout, or stderr as a flat string.

Parameters:fd – A file descriptor.
Returns:The concrete content.
Return type:str
class angr.state_plugins.filesystem.SimFilesystem(files=None, pathsep=None, cwd=None, mountpoints=None)

Bases: angr.state_plugins.plugin.SimStatePlugin

angr’s emulated filesystem. Available as state.fs. When constructing, all parameters are optional.

Parameters:
  • files – A mapping from filepath to SimFile
  • pathsep – The character used to separate path elements, default forward slash.
  • cwd – The path of the current working directory to use
  • mountpoints – A mapping from filepath to SimMountpoint
Variables:
  • pathsep – The current pathsep
  • cwd – The current working directory
  • unlinks – A list of unlink operations, tuples of filename and simfile. Be careful, this list is shallow-copied from successor to successor, so don’t mutate anything in it without copying.
set_state(state)
copy(memo=None, **kwargs)
merge(others, merge_conditions, common_ancestor=None)
widen(others)
chdir(path)

Changes the current directory to the given path

get(path)

Get a file from the filesystem. Returns a SimFile or None.

insert(path, simfile)

Insert a file into the filesystem. Returns whether the operation was successful.

delete(path)

Remove a file from the filesystem. Returns whether the operation was successful.

This will add a fs_unlink event with the path of the file and also the index into the unlinks list.

mount(path, mount)

Add a mountpoint to the filesystem.

unmount(path)

Remove a mountpoint from the filesystem.

get_mountpoint(path)

Look up the mountpoint servicing the given path.

Returns:A tuple of the mount and a list of path elements traversing from the mountpoint to the specified file.
class angr.state_plugins.filesystem.SimMount

Bases: angr.state_plugins.plugin.SimStatePlugin

This is the base class for “mount points” in angr’s simulated filesystem. Subclass this class and give it to the filesystem to intercept all file creations and opens below the mountpoint. Since this a SimStatePlugin you may also want to implement set_state, copy, merge, etc.

get(_path_elements)

Implement this function to instrument file lookups.

Parameters:path_elements – A list of path elements traversing from the mountpoint to the file
Returns:A SimFile, or None
insert(_path_elements, simfile)

Implement this function to instrument file creation.

Parameters:
  • path_elements – A list of path elements traversing from the mountpoint to the file
  • simfile – The file to insert
Returns:

A bool indicating whether the insert occured

delete(_path_elements)

Implement this function to instrument file deletion.

Parameters:path_elements – A list of path elements traversing from the mountpoint to the file
Returns:A bool indicating whether the delete occured
class angr.state_plugins.filesystem.SimHostFilesystem(host_path, pathsep='/')

Bases: angr.state_plugins.filesystem.SimMount

Simulated mount that makes some piece from the host filesystem available to the guest.

Parameters:
  • host_path (str) – The path on the host to mount
  • pathsep (str) – The host path separator character, default os.path.sep
get(path_elements)
insert(path_elements, simfile)
delete(path_elements)
copy(memo=None, **kwargs)
set_state(state)
merge(others, merge_conditions, common_ancestor=None)
widen(others)
angr.state_plugins.solver.timed_function(f)
angr.state_plugins.solver.enable_timing()
angr.state_plugins.solver.disable_timing()
angr.state_plugins.solver.error_converter(f)
angr.state_plugins.solver.concrete_path_bool(f)
angr.state_plugins.solver.concrete_path_not_bool(f)
angr.state_plugins.solver.concrete_path_scalar(f)
angr.state_plugins.solver.concrete_path_tuple(f)
angr.state_plugins.solver.concrete_path_list(f)
class angr.state_plugins.solver.SimSolver(solver=None, all_variables=None, temporal_tracked_variables=None, eternal_tracked_variables=None)

Bases: angr.state_plugins.plugin.SimStatePlugin

This is the plugin you’ll use to interact with symbolic variables, creating them and evaluating them. It should be available on a state as state.solver.

Any top-level variable of the claripy module can be accessed as a property of this object.

reload_solver()

Reloads the solver. Useful when changing solver options.

get_variables(*keys)

Iterate over all variables for which their tracking key is a prefix of the values provided.

Elements are a tuple, the first element is the full tracking key, the second is the symbol.

>>> list(s.solver.get_variables('mem'))
[(('mem', 0x1000), <BV64 mem_1000_4_64>), (('mem', 0x1008), <BV64 mem_1008_5_64>)]
>>> list(s.solver.get_variables('file'))
[(('file', 1, 0), <BV8 file_1_0_6_8>), (('file', 1, 1), <BV8 file_1_1_7_8>), (('file', 2, 0), <BV8 file_2_0_8_8>)]
>>> list(s.solver.get_variables('file', 2))
[(('file', 2, 0), <BV8 file_2_0_8_8>)]
>>> list(s.solver.get_variables())
[(('mem', 0x1000), <BV64 mem_1000_4_64>), (('mem', 0x1008), <BV64 mem_1008_5_64>), (('file', 1, 0), <BV8 file_1_0_6_8>), (('file', 1, 1), <BV8 file_1_1_7_8>), (('file', 2, 0), <BV8 file_2_0_8_8>)]
register_variable(v, key, eternal=True)

Register a value with the variable tracking system

Parameters:
  • v – The BVS to register
  • key – A tuple to register the variable under
Parma eternal:

Whether this is an eternal variable, default True. If False, an incrementing counter will be appended to the key.

describe_variables(v)

Given an AST, iterate over all the keys of all the BVS leaves in the tree which are registered.

Unconstrained(name, bits, uninitialized=True, inspect=True, events=True, key=None, eternal=False, **kwargs)

Creates an unconstrained symbol or a default concrete value (0), based on the state options.

Parameters:
  • name – The name of the symbol.
  • bits – The size (in bits) of the symbol.
  • uninitialized – Whether this value should be counted as an “uninitialized” value in the course of an analysis.
  • inspect – Set to False to avoid firing SimInspect breakpoints
  • events – Set to False to avoid generating a SimEvent for the occasion
  • key – Set this to a tuple of increasingly specific identifiers (for example, ('mem', 0xffbeff00) or ('file', 4, 0x20) to cause it to be tracked, i.e. accessable through solver.get_variables.
  • eternal – Set to True in conjunction with setting a key to cause all states with the same ancestry to retrieve the same symbol when trying to create the value. If False, a counter will be appended to the key.
Returns:

an unconstrained symbol (or a concrete value of 0).

BVS(name, size, min=None, max=None, stride=None, uninitialized=False, explicit_name=None, key=None, eternal=False, inspect=True, events=True, **kwargs)

Creates a bit-vector symbol (i.e., a variable). Other keyword parameters are passed directly on to the constructor of claripy.ast.BV.

Parameters:
  • name – The name of the symbol.
  • size – The size (in bits) of the bit-vector.
  • min – The minimum value of the symbol. Note that this only work when using VSA.
  • max – The maximum value of the symbol. Note that this only work when using VSA.
  • stride – The stride of the symbol. Note that this only work when using VSA.
  • uninitialized – Whether this value should be counted as an “uninitialized” value in the course of an analysis.
  • explicit_name – Set to True to prevent an identifier from appended to the name to ensure uniqueness.
  • key – Set this to a tuple of increasingly specific identifiers (for example, ('mem', 0xffbeff00) or ('file', 4, 0x20) to cause it to be tracked, i.e. accessable through solver.get_variables.
  • eternal – Set to True in conjunction with setting a key to cause all states with the same ancestry to retrieve the same symbol when trying to create the value. If False, a counter will be appended to the key.
  • inspect – Set to False to avoid firing SimInspect breakpoints
  • events – Set to False to avoid generating a SimEvent for the occasion
Returns:

A BV object representing this symbol.

copy(memo=None, **kwargs)
merge(others, merge_conditions, common_ancestor=None)
widen(others)
downsize()

Frees memory associated with the constraint solver by clearing all of its internal caches.

constraints

Returns the constraints of the state stored by the solver.

eval_to_ast(e, n, extra_constraints=(), exact=None)

Evaluate an expression, using the solver if necessary. Returns AST objects.

Parameters:
  • e – the expression
  • n – the number of desired solutions
  • extra_constraints – extra constraints to apply to the solver
  • exact – if False, returns approximate solutions
Returns:

a tuple of the solutions, in the form of claripy AST nodes

Return type:

tuple

max(e, extra_constraints=(), exact=None)

Return the maximum value of expression e.

:param e : expression (an AST) to evaluate :param extra_constraints: extra constraints (as ASTs) to add to the solver for this solve :param exact : if False, return approximate solutions. :return: the maximum possible value of e (backend object)

min(e, extra_constraints=(), exact=None)

Return the minimum value of expression e.

:param e : expression (an AST) to evaluate :param extra_constraints: extra constraints (as ASTs) to add to the solver for this solve :param exact : if False, return approximate solutions. :return: the minimum possible value of e (backend object)

solution(e, v, extra_constraints=(), exact=None)

Return True if v is a solution of expr with the extra constraints, False otherwise.

Parameters:
  • e – An expression (an AST) to evaluate
  • v – The proposed solution (an AST)
  • extra_constraints – Extra constraints (as ASTs) to add to the solver for this solve.
  • exact – If False, return approximate solutions.
Returns:

True if v is a solution of expr, False otherwise

is_true(e, extra_constraints=(), exact=None)

If the expression provided is absolutely, definitely a true boolean, return True. Note that returning False doesn’t necessarily mean that the expression can be false, just that we couldn’t figure that out easily.

Parameters:
  • e – An expression (an AST) to evaluate
  • extra_constraints – Extra constraints (as ASTs) to add to the solver for this solve.
  • exact – If False, return approximate solutions.
Returns:

True if v is definitely true, False otherwise

is_false(e, extra_constraints=(), exact=None)

If the expression provided is absolutely, definitely a false boolean, return True. Note that returning False doesn’t necessarily mean that the expression can be true, just that we couldn’t figure that out easily.

Parameters:
  • e – An expression (an AST) to evaluate
  • extra_constraints – Extra constraints (as ASTs) to add to the solver for this solve.
  • exact – If False, return approximate solutions.
Returns:

True if v is definitely false, False otherwise

unsat_core(extra_constraints=())

This function returns the unsat core from the backend solver.

Parameters:extra_constraints – Extra constraints (as ASTs) to add to the solver for this solve.
Returns:The unsat core.
satisfiable(extra_constraints=(), exact=None)

This function does a constraint check and checks if the solver is in a sat state.

Parameters:
  • extra_constraints – Extra constraints (as ASTs) to add to s for this solve
  • exact – If False, return approximate solutions.
Returns:

True if sat, otherwise false

add(*constraints)

Add some constraints to the solver.

Parameters:constraints – Pass any constraints that you want to add (ASTs) as varargs.
eval_upto(e, n, cast_to=None, **kwargs)

Evaluate an expression, using the solver if necessary. Returns primitives as specified by the cast_to parameter. Only certain primitives are supported, check the implementation of _cast_to to see which ones.

Parameters:
  • e – the expression
  • n – the number of desired solutions
  • extra_constraints – extra constraints to apply to the solver
  • exact – if False, returns approximate solutions
  • cast_to – A type to cast the resulting values to
Returns:

a tuple of the solutions, in the form of Python primitives

Return type:

tuple

eval(e, **kwargs)

Evaluate an expression to get any possible solution. The desired output types can be specified using the cast_to parameter. extra_constraints can be used to specify additional constraints the returned values must satisfy.

Parameters:
  • e – the expression to get a solution for
  • kwargs – Any additional kwargs will be passed down to eval_upto
Raises:

SimUnsatError – if no solution could be found satisfying the given constraints

Returns:

eval_one(e, **kwargs)

Evaluate an expression to get the only possible solution. Errors if either no or more than one solution is returned. A kwarg parameter default can be specified to be returned instead of failure!

Parameters:
  • e – the expression to get a solution for
  • default – A value can be passed as a kwarg here. It will be returned in case of failure.
  • kwargs – Any additional kwargs will be passed down to eval_upto
Raises:
  • SimUnsatError – if no solution could be found satisfying the given constraints
  • SimValueError – if more than one solution was found to satisfy the given constraints
Returns:

The value for e

eval_atmost(e, n, **kwargs)

Evaluate an expression to get at most n possible solutions. Errors if either none or more than n solutions are returned.

Parameters:
  • e – the expression to get a solution for
  • n – the inclusive upper limit on the number of solutions
  • kwargs – Any additional kwargs will be passed down to eval_upto
Raises:
  • SimUnsatError – if no solution could be found satisfying the given constraints
  • SimValueError – if more than n solutions were found to satisfy the given constraints
Returns:

The solutions for e

eval_atleast(e, n, **kwargs)

Evaluate an expression to get at least n possible solutions. Errors if less than n solutions were found.

Parameters:
  • e – the expression to get a solution for
  • n – the inclusive lower limit on the number of solutions
  • kwargs – Any additional kwargs will be passed down to eval_upto
Raises:
  • SimUnsatError – if no solution could be found satisfying the given constraints
  • SimValueError – if less than n solutions were found to satisfy the given constraints
Returns:

The solutions for e

eval_exact(e, n, **kwargs)

Evaluate an expression to get exactly the n possible solutions. Errors if any number of solutions other than n was found to exist.

Parameters:
  • e – the expression to get a solution for
  • n – the inclusive lower limit on the number of solutions
  • kwargs – Any additional kwargs will be passed down to eval_upto
Raises:
  • SimUnsatError – if no solution could be found satisfying the given constraints
  • SimValueError – if any number of solutions other than n were found to satisfy the given constraints
Returns:

The solutions for e

min_int(e, extra_constraints=(), exact=None)

Return the minimum value of expression e.

:param e : expression (an AST) to evaluate :param extra_constraints: extra constraints (as ASTs) to add to the solver for this solve :param exact : if False, return approximate solutions. :return: the minimum possible value of e (backend object)

max_int(e, extra_constraints=(), exact=None)

Return the maximum value of expression e.

:param e : expression (an AST) to evaluate :param extra_constraints: extra constraints (as ASTs) to add to the solver for this solve :param exact : if False, return approximate solutions. :return: the maximum possible value of e (backend object)

unique(e, **kwargs)

Returns True if the expression e has only one solution by querying the constraint solver. It does also add that unique solution to the solver’s constraints.

symbolic(e)

Returns True if the expression e is symbolic.

single_valued(e)

Returns True whether e is a concrete value or is a value set with only 1 possible value. This differs from unique in that this does not query the constraint solver.

simplify(e=None)

Simplifies e. If e is None, simplifies the constraints of this state.

variables(e)

Returns the symbolic variables present in the AST of e.

class angr.state_plugins.log.SimStateLog(log=None)

Bases: angr.state_plugins.plugin.SimStatePlugin

actions
add_event(event_type, **kwargs)
add_action(action)
extend_actions(new_actions)
events_of_type(event_type)
actions_of_type(action_type)
fresh_constraints
copy(memo=None, **kwargs)
merge(others, merge_conditions, common_ancestor=None)
widen(others)
clear()
class angr.state_plugins.callstack.CallStack(call_site_addr=0, func_addr=0, stack_ptr=0, ret_addr=0, jumpkind='Ijk_Call', next_frame=None)

Bases: angr.state_plugins.plugin.SimStatePlugin

Stores the address of the function you’re in and the value of SP at the VERY BOTTOM of the stack, i.e. points to the return address.

call_target
return_target
stack_pointer
copy(memo=None, **kwargs)
set_state(state)
merge(others, merge_conditions, common_ancestor=None)
widen(others)
current_function_address

Address of the current function.

Returns:the address of the function
Return type:int
current_stack_pointer

Get the value of the stack pointer.

Returns:Value of the stack pointer
Return type:int
current_return_target

Get the return target.

Returns:The address of return target.
Return type:int
static stack_suffix_to_string(stack_suffix)

Convert a stack suffix to a human-readable string representation. :param tuple stack_suffix: The stack suffix. :return: A string representation :rtype: str

top

Returns the element at the top of the callstack without removing it.

Returns:A CallStack.
push(cf)

Push the frame cf onto the stack. Return the new stack.

pop()

Pop the top frame from the stack. Return the new stack.

call(callsite_addr, addr, retn_target=None, stack_pointer=None)

Push a stack frame into the call stack. This method is called when calling a function in CFG recovery.

Parameters:
  • callsite_addr (int) – Address of the call site
  • addr (int) – Address of the call target
  • or None retn_target (int) – Address of the return target
  • stack_pointer (int) – Value of the stack pointer
Returns:

None

ret(retn_target=None)

Pop one or many call frames from the stack. This method is called when returning from a function in CFG recovery.

Parameters:retn_target (int) – The target to return to.
Returns:None
dbg_repr()

Debugging representation of this CallStack object.

Returns:Details of this CalLStack
Return type:str
stack_suffix(context_sensitivity_level)

Generate the stack suffix. A stack suffix can be used as the key to a SimRun in CFG recovery.

Parameters:context_sensitivity_level (int) – Level of context sensitivity.
Returns:A tuple of stack suffix.
Return type:tuple
class angr.state_plugins.callstack.CallStackAction(callstack_hash, callstack_depth, action, callframe=None, ret_site_addr=None)

Bases: object

Used in callstack backtrace, which is a history of callstacks along a path, to record individual actions occurred each time the callstack is changed.

class angr.state_plugins.fast_memory.SimFastMemory(memory_backer=None, memory_id=None, endness=None, contents=None, width=None, uninitialized_read_handler=None)

Bases: angr.storage.memory.SimMemory

set_state(state)
copy(memo=None, **kwargs)
changed_bytes(other)

Gets the set of changed bytes between self and other.

class angr.state_plugins.history.SimStateHistory(parent=None, clone=None)

Bases: angr.state_plugins.plugin.SimStatePlugin

This class keeps track of historically-relevant information for paths.

STRONGREF_STATE = True
init_state()
set_strongref_state(state)
addr
merge(others, merge_conditions, common_ancestor=None)
widen(others)
copy(memo=None, **kwargs)
trim()

Discard the ancestry of this state.

filter_actions(block_addr=None, block_stmt=None, insn_addr=None, read_from=None, write_to=None)

Filter self.actions based on some common parameters.

Parameters:
  • block_addr – Only return actions generated in blocks starting at this address.
  • block_stmt – Only return actions generated in the nth statement of each block.
  • insn_addr – Only return actions generated in the assembly instruction at this address.
  • read_from – Only return actions that perform a read from the specified location.
  • write_to – Only return actions that perform a write to the specified location.

Notes: If IR optimization is turned on, reads and writes may not occur in the instruction they originally came from. Most commonly, If a register is read from twice in the same block, the second read will not happen, instead reusing the temp the value is already stored in.

Valid values for read_from and write_to are the string literals ‘reg’ or ‘mem’ (matching any read or write to registers or memory, respectively), any string (representing a read or write to the named register), and any integer (representing a read or write to the memory at this address).

demote()

Demotes this history node, causing it to drop the strong state reference.

reachable()
add_event(event_type, **kwargs)
add_action(action)
extend_actions(new_actions)
recent_constraints
recent_actions
block_count
lineage
parents
events
actions
jumpkinds
jump_guards
jump_targets
descriptions
bbl_addrs
ins_addrs
stack_actions
closest_common_ancestor(other)

Find the common ancestor between this history node and ‘other’.

Parameters:other – the PathHistory to find a common ancestor with.
Returns:the common ancestor SimStateHistory, or None if there isn’t one
constraints_since(other)

Returns the constraints that have been accumulated since other.

Parameters:other – a prior PathHistory object
Returns:a list of constraints
make_child()
class angr.state_plugins.history.TreeIter(start, end=None)

Bases: object

hardcopy
count(v)

Count occurrences of value v in the entire history. Note that the subclass must implement the __reversed__ method, otherwise an exception will be thrown. :param object v: The value to look for :return: The number of occurrences :rtype: int

class angr.state_plugins.history.HistoryIter(start, end=None)

Bases: angr.state_plugins.history.TreeIter

class angr.state_plugins.history.LambdaAttrIter(start, f, **kwargs)

Bases: angr.state_plugins.history.TreeIter

class angr.state_plugins.history.LambdaIterIter(start, f, reverse=True, **kwargs)

Bases: angr.state_plugins.history.LambdaAttrIter

class angr.state_plugins.gdb.GDB(omit_fp=False, adjust_stack=False)

Bases: angr.state_plugins.plugin.SimStatePlugin

Initialize or update a state from gdb dumps of the stack, heap, registers and data (or arbitrary) segments.

Parameters:
  • omit_fp – The frame pointer register is used for something else. (i.e. –omit_frame_pointer)
  • adjust_stack – Use different stack addresses than the gdb session (not recommended).
set_stack(stack_dump, stack_top)

Stack dump is a dump of the stack from gdb, i.e. the result of the following gdb command :

dump binary memory [stack_dump] [begin_addr] [end_addr]

We set the stack to the same addresses as the gdb session to avoid pointers corruption.

Parameters:
  • stack_dump – The dump file.
  • stack_top – The address of the top of the stack in the gdb session.
set_heap(heap_dump, heap_base)

Heap dump is a dump of the heap from gdb, i.e. the result of the following gdb command:

dump binary memory [stack_dump] [begin] [end]

Parameters:
  • heap_dump – The dump file.
  • heap_base – The start address of the heap in the gdb session.
set_data(addr, data_dump)

Update any data range (most likely use is the data segments of loaded objects)

set_regs(regs_dump)

Initialize register values within the state

Parameters:regs_dump – The output of info registers in gdb.
copy(memo=None, **kwargs)
class angr.state_plugins.cgc.SimStateCGC

Bases: angr.state_plugins.plugin.SimStatePlugin

This state plugin keeps track of CGC state.

peek_input()
discard_input(num_bytes)
peek_output()
discard_output(num_bytes)
addr_invalid(a)
copy(memo=None, **kwargs)
merge(others, merge_conditions, common_ancestor=None)
widen(others)
get_max_sinkhole(length)

Find a sinkhole which is large enough to support length bytes.

This uses first-fit. The first sinkhole (ordered in descending order by their address) which can hold length bytes is chosen. If there are more than length bytes in the sinkhole, a new sinkhole is created representing the remaining bytes while the old sinkhole is removed.

add_sinkhole(address, length)

Add a sinkhole.

Allow the possibility for the program to reuse the memory represented by the address length pair.

angr.state_plugins.trace_additions.l = <Logger angr.state_plugins.trace_additions (WARNING)>

This file contains objects to track additional information during a trace or modify symbolic variables during a trace.

The ChallRespInfo plugin tracks variables in stdin and stdout to enable handling of challenge response It handles atoi/int2str in a special manner since path constraints will usually prevent their values from being modified

The Zen plugin simplifies expressions created from variables in the flag page (losing some accuracy) to avoid situations where they become to complex for z3, but the actual equation doesn’t matter much. This can happen in challenge response if all of the values in the flag page are multiplied together before being printed.

class angr.state_plugins.trace_additions.FormatInfo

Bases: object

copy()
compute(state)
get_type()
class angr.state_plugins.trace_additions.FormatInfoStrToInt(addr, func_name, str_arg_num, base, base_arg, allows_negative)

Bases: angr.state_plugins.trace_additions.FormatInfo

copy()
compute(state)
get_type()
class angr.state_plugins.trace_additions.FormatInfoIntToStr(addr, func_name, int_arg_num, str_dst_num, base, base_arg)

Bases: angr.state_plugins.trace_additions.FormatInfo

copy()
compute(state)
get_type()
class angr.state_plugins.trace_additions.FormatInfoDontConstrain(addr, func_name, check_symbolic_arg)

Bases: angr.state_plugins.trace_additions.FormatInfo

copy()
compute(state)
get_type()
angr.state_plugins.trace_additions.int2base(x, base)
angr.state_plugins.trace_additions.generic_info_hook(state)
angr.state_plugins.trace_additions.end_info_hook(state)
angr.state_plugins.trace_additions.exit_hook(state)
angr.state_plugins.trace_additions.syscall_hook(state)
angr.state_plugins.trace_additions.constraint_hook(state)
class angr.state_plugins.trace_additions.ChallRespInfo

Bases: angr.state_plugins.plugin.SimStatePlugin

This state plugin keeps track of the reads and writes to symbolic addresses

copy(memo=None, **kwargs)
merge(others, merge_conditions, common_ancestor=None)
widen(others)
static get_byte(var_name)
lookup_original(replacement)
pop_from_backup()
get_stdin_indices(variable)
get_stdout_indices(variable)
get_real_len(input_val, base, result_bv, allows_negative)
get_possible_len(input_val, base, allows_negative)
get_same_length_constraints()
static atoi_dumps(state, require_same_length=True)
static prep_tracer(state, format_infos=None)
angr.state_plugins.trace_additions.zen_hook(state, expr)
angr.state_plugins.trace_additions.zen_memory_write(state)
angr.state_plugins.trace_additions.zen_register_write(state)
class angr.state_plugins.trace_additions.ZenPlugin(max_depth=13)

Bases: angr.state_plugins.plugin.SimStatePlugin

static get_flag_rand_args(expr)
get_expr_depth(expr)
copy(memo=None, **kwargs)
merge(others, merge_conditions, common_ancestor=None)
widen(others)
get_flag_bytes(ast)
filter_constraints(constraints)
analyze_transmit(state, buf)
static prep_tracer(state)
class angr.state_plugins.globals.SimStateGlobals(backer=None)

Bases: angr.state_plugins.plugin.SimStatePlugin

set_state(state)
merge(others, merge_conditions, common_ancestor=None)
widen(others)
keys()
values()
items()
get(k, alt=None)
pop(k, alt=None)
copy(memo=None, **kwargs)
class angr.state_plugins.uc_manager.SimUCManager(man=None)

Bases: angr.state_plugins.plugin.SimStatePlugin

assign(dst_addr_ast)

Assign a new region for under-constrained symbolic execution.

Parameters:dst_addr_ast – the symbolic AST which address of the new allocated region will be assigned to.
Returns:as ast of memory address that points to a new region
copy(memo=None, **kwargs)
get_alloc_depth(addr)
is_bounded(ast)

Test whether an AST is bounded by any existing constraint in the related solver.

Parameters:ast – an claripy.AST object
Returns:True if there is at least one related constraint, False otherwise
set_state(state)
class angr.state_plugins.scratch.SimStateScratch(scratch=None)

Bases: angr.state_plugins.plugin.SimStatePlugin

priv
push_priv(priv)
pop_priv()
tmp_expr(tmp)

Returns the Claripy expression of a VEX temp value.

Parameters:
  • tmp – the number of the tmp
  • simplify – simplify the tmp before returning it
Returns:

a Claripy expression of the tmp

store_tmp(tmp, content, reg_deps=None, tmp_deps=None, action_holder=None)

Stores a Claripy expression in a VEX temp value. If in symbolic mode, this involves adding a constraint for the tmp’s symbolic variable.

Parameters:
  • tmp – the number of the tmp
  • content – a Claripy expression of the content
  • reg_deps – the register dependencies of the content
  • tmp_deps – the temporary value dependencies of the content
copy(memo=None, **kwargs)
merge(others, merge_conditions, common_ancestor=None)
widen(others)
clear()
class angr.state_plugins.preconstrainer.SimStatePreconstrainer(constrained_addrs=None)

Bases: angr.state_plugins.plugin.SimStatePlugin

This state plugin manages the concept of preconstraining - adding constraints which you would like to remove later.

:param constrained_addrs : SimActions for memory operations whose addresses should be constrained during crash analysis

merge(others, merge_conditions, common_ancestor=None)
widen(others)
copy(memo=None, **kwargs)
preconstrain(value, variable)

Add a preconstraint that variable == value to the state.

Parameters:
  • value – The concrete value. Can be a bitvector or a bytestring or an integer.
  • variable – The BVS to preconstrain.
preconstrain_file(content, simfile, set_length=False)

Preconstrain the contents of a file.

Parameters:
  • content – The content to preconstrain the file to. Can be a bytestring or a list thereof.
  • simfile – The actual simfile to preconstrain
preconstrain_flag_page(magic_content)

Preconstrain the data in the flag page.

Parameters:magic_content – The content of the magic page as a bytestring.
remove_preconstraints(to_composite_solver=True, simplify=True)
reconstrain()

Re-apply preconstraints to improve solver time, hopefully these constraints still allow us to do meaningful things to state.

class angr.state_plugins.unicorn_engine.MEM_PATCH

Bases: _ctypes.Structure

address

Structure/Union member

length

Structure/Union member

next

Structure/Union member

class angr.state_plugins.unicorn_engine.TRANSMIT_RECORD

Bases: _ctypes.Structure

count

Structure/Union member

data

Structure/Union member

class angr.state_plugins.unicorn_engine.STOP

Bases: object

STOP_NORMAL = 0
STOP_STOPPOINT = 1
STOP_SYMBOLIC_MEM = 2
STOP_SYMBOLIC_REG = 3
STOP_ERROR = 4
STOP_SYSCALL = 5
STOP_EXECNONE = 6
STOP_ZEROPAGE = 7
STOP_NOSTART = 8
STOP_SEGFAULT = 9
STOP_ZERO_DIV = 10
STOP_NODECODE = 11
static name_stop(num)
exception angr.state_plugins.unicorn_engine.MemoryMappingError

Bases: Exception

exception angr.state_plugins.unicorn_engine.AccessingZeroPageError

Bases: angr.state_plugins.unicorn_engine.MemoryMappingError

exception angr.state_plugins.unicorn_engine.FetchingZeroPageError

Bases: angr.state_plugins.unicorn_engine.MemoryMappingError

exception angr.state_plugins.unicorn_engine.SegfaultError

Bases: angr.state_plugins.unicorn_engine.MemoryMappingError

exception angr.state_plugins.unicorn_engine.MixedPermissonsError

Bases: angr.state_plugins.unicorn_engine.MemoryMappingError

class angr.state_plugins.unicorn_engine.AggressiveConcretizationAnnotation(addr)

Bases: claripy.annotation.SimplificationAvoidanceAnnotation

class angr.state_plugins.unicorn_engine.Uniwrapper(arch, cache_key)

Bases: unicorn.unicorn.Uc

hook_add(htype, callback, user_data=None, begin=1, end=0, arg1=0)
hook_del(h)
mem_map(addr, size, perms=7)
mem_unmap(addr, size)
mem_reset()
hook_reset()
reset()
class angr.state_plugins.unicorn_engine.Unicorn(syscall_hooks=None, cache_key=None, unicount=None, symbolic_var_counts=None, symbolic_inst_counts=None, concretized_asts=None, always_concretize=None, never_concretize=None, concretize_at=None, concretization_threshold_memory=None, concretization_threshold_registers=None, concretization_threshold_instruction=None, cooldown_symbolic_registers=100, cooldown_symbolic_memory=100, cooldown_nonunicorn_blocks=100, cooldown_stop_point=1, max_steps=1000000)

Bases: angr.state_plugins.plugin.SimStatePlugin

setup the unicorn engine for a state

Initializes the Unicorn plugin for angr. This plugin handles communication with UnicornEngine.

UC_CONFIG = {}
copy(memo=None, **kwargs)
merge(others, merge_conditions, common_ancestor=None)
widen(others)
set_state(state)
uc
static delete_uc()
set_stops(stop_points)
set_tracking(track_bbls, track_stack)
hook()
uncache_page(addr)
setup()
start(step=None)
finish()
destroy()
set_regs()

setting unicorn registers

setup_gdt(fs, gs, fs_size=4294967295, gs_size=4294967295)
static create_selector(idx, flags)
static create_gdt_entry(base, limit, access, flags)
read_msr(msr=3221225728)
write_msr(val, msr=3221225728)
reg_blacklist = ('cs', 'ds', 'es', 'fs', 'gs', 'ss', 'mm0', 'mm1', 'mm2', 'mm3', 'mm4', 'mm5', 'mm6', 'mm7')
get_regs()

loading registers from unicorn

class angr.state_plugins.loop_data.SimStateLoopData(back_edge_trip_counts=None, header_trip_counts=None, current_loop=None)

Bases: angr.state_plugins.plugin.SimStatePlugin

This class keeps track of loop-related information for states. Note that we have 2 counters for loop iterations (trip counts): the first recording the number of times one of the back edges (or continue edges) of a loop is taken, whereas the second recording the number of times the loop header (or loop entry) is executed. These 2 counters may differ since compilers usually optimize loops hence completely change the loop structure at the binary level. This is supposed to be used with LoopSeer exploration technique, which monitors loop execution. For the moment, the only thing we want to analyze is loop trip counts, but nothing prevents us from extending this plugin for other loop analyses.

Parameters:
  • back_edge_trip_counts – Dictionary that stores back edge based trip counts for each loop. Keys are address of loop headers.
  • header_trip_counts – Dictionary that stores header based trip counts for each loop. Keys are address of loop headers.
  • current_loop – List of currently running loops. Each element is a tuple (loop object, list of loop exits).
merge(others, merge_conditions, common_ancestor=None)
widen(others)
copy(memo=None, **kwargs)

Storage

class angr.state_plugins.view.SimRegNameView

Bases: angr.state_plugins.plugin.SimStatePlugin

copy(memo=None, **kwargs)
merge(others, merge_conditions, common_ancestor=None)
widen(others)
get(reg_name)
class angr.state_plugins.view.SimMemView(ty=None, addr=None, state=None)

Bases: angr.state_plugins.plugin.SimStatePlugin

This is a convenient interface with which you can access a program’s memory.

The interface works like this:

  • You first use [array index notation] to specify the address you’d like to load from
  • If at that address is a pointer, you may access the deref property to return a SimMemView at the address present in memory.
  • You then specify a type for the data by simply accesing a property of that name. For a list of supported types, look at state.mem.types.
  • You can then refine the type. Any type may support any refinement it likes. Right now the only refinements supported are that you may access any member of a struct by its member name, and you may index into a string or array to access that element.
  • If the address you specified initially points to an array of that type, you can say .array(n) to view the data as an array of n elements.
  • Finally, extract the structured data with .resolved or .concrete. .resolved will return bitvector values, while .concrete will return integer, string, array, etc values, whatever best represents the data.
  • Alternately, you may store a value to memory, by assigning to the chain of properties that you’ve constructed. Note that because of the way python works, x = s.mem[...].prop; x = val will NOT work, you must say s.mem[...].prop = val.

For example:

>>> s.mem[0x601048].long
<long (64 bits) <BV64 0x4008d0> at 0x601048>
>>> s.mem[0x601048].long.resolved
<BV64 0x4008d0>
>>> s.mem[0x601048].deref
<<untyped> <unresolvable> at 0x4008d0>
>>> s.mem[0x601048].deref.string.concrete
'SOSNEAKY'
set_state(state)
types = {'byte': uint8_t, 'char': char, 'double': double, 'dword': uint32_t, 'float': float, 'int': int, 'int16_t': int16_t, 'int32_t': int32_t, 'int64_t': int64_t, 'int8_t': int8_t, 'long': long, 'long int': long, 'long long': long long, 'long long int': long long, 'ptrdiff_t': long, 'qword': uint64_t, 'short': short, 'short int': short, 'signed char': char, 'signed int': int, 'signed long': long, 'signed long int': long, 'signed long long': long long, 'signed long long int': long long, 'signed short': short, 'signed short int': short, 'size_t': size_t, 'ssize': size_t, 'ssize_t': size_t, 'string': string_t, 'struct iovec': struct iovec, 'struct timespec': struct timespec, 'struct timeval': struct timeval, 'time_t': long, 'uint16_t': uint16_t, 'uint32_t': uint32_t, 'uint64_t': uint64_t, 'uint8_t': uint8_t, 'uintptr_t': unsigned long, 'unsigned char': char, 'unsigned int': unsigned int, 'unsigned long': unsigned long, 'unsigned long int': unsigned long, 'unsigned long long': unsigned long long, 'unsigned long long int': unsigned long long, 'unsigned short': unsigned short, 'unsigned short int': unsigned short, 'void': BOT, 'word': uint16_t, 'wstring': wstring_t}
state = None
copy(memo=None, **kwargs)
merge(others, merge_conditions, common_ancestor=None)
widen(others)
resolvable
resolved
concrete
deref
array(n)
store(value)
class angr.state_plugins.view.StructMode(view)

Bases: object

class angr.storage.file.Flags

Bases: object

O_RDONLY = 0
O_WRONLY = 1
O_RDWR = 2
O_ACCMODE = 3
O_APPEND = 4096
O_ASYNC = 64
O_CLOEXEC = 512
O_CREAT = 256
O_DIRECT = 262144
O_DIRECTORY = 2097152
O_EXCL = 2048
O_LARGEFILE = 1048576
O_NOATIME = 16777216
O_NOCTTY = 1024
O_NOFOLLOW = 4194304
O_NONBLOCK = 8192
O_NODELAY = 8192
O_SYNC = 67174400
O_TRUNC = 1024
class angr.storage.file.SimFileBase(name, writable=True, ident=None, concrete=False, **kwargs)

Bases: angr.state_plugins.plugin.SimStatePlugin

SimFiles are the storage mechanisms used by SimFileDescriptors.

Different types of SimFiles can have drastically different interfaces, and as a result there’s not much that can be specified on this base class. All the read and write methods take a pos argument, which may have different semantics per-class. 0 will always be a valid position to use, though, and the next position you should use is part of the return tuple.

Some simfiles are “streams”, meaning that the position that reads come from is determined not by the position you pass in (it will in fact be ignored), but by an internal variable. This is stored as .pos if you care to read it. Don’t write to it. The same lack-of-semantics applies to this field as well.

Variables:
  • name – The name of the file. Purely for cosmetic purposes
  • ident – The identifier of the file, typically autogenerated from the name and a nonce. Purely for cosmetic purposes, but does appear in symbolic values autogenerated in the file.
  • seekable – Bool indicating whether seek operations on this file should succeed. If this is True, then pos must be a number of bytes from the start of the file.
  • writable – Bool indicating whether writing to this file is allowed.
  • pos – If the file is a stream, this will be the current position. Otherwise, None.
  • concrete – Whether or not this file contains mostly concrete data. Will be used by some SimProcedures to choose how to handle variable-length operations like fgets.
seekable = False
pos = None
static make_ident(name)
concretize(**kwargs)

Return a concretization of the contents of the file. The type of the return value of this method will vary depending on which kind of SimFile you’re using.

read(pos, size, **kwargs)

Read some data from the file.

Parameters:
  • pos – The offset in the file to read from.
  • size – The size to read. May be symbolic.
Returns:

A tuple of the data read (a bitvector of the length that is the maximum length of the read), the actual size of the read, and the new file position pointer.

write(pos, data, size=None, **kwargs)

Write some data to the file.

Parameters:
  • pos – The offset in the file to write to. May be ignored if the file is a stream or device.
  • data – The data to write as a bitvector
  • size – The optional size of the data to write. If not provided will default to the length of the data. Must be constrained to less than or equal to the size of the data.
Returns:

The new file position pointer.

size

The number of data bytes stored by the file at present. May be a symbolic value.

class angr.storage.file.SimFile(name, content=None, size=None, has_end=None, seekable=True, writable=True, ident=None, concrete=None, **kwargs)

Bases: angr.storage.file.SimFileBase, angr.state_plugins.symbolic_memory.SimSymbolicMemory

The normal SimFile is meant to model files on disk. It subclasses SimSymbolicMemory so loads and stores to/from it are very simple.

Parameters:
  • name – The name of the file
  • content – Optional initial content for the file as a string or bitvector
  • size – Optional size of the file. If content is not specified, it defaults to zero
  • has_end – Whether the size boundary is treated as the end of the file or a frontier at which new content will be generated. If unspecified, will pick its value based on options.FILES_HAVE_EOF. Another caveat is that if the size is also unspecified this value will default to False.
  • seekable – Optional bool indicating whether seek operations on this file should succeed, default True.
  • writable – Whether writing to this file is allowed
  • concrete – Whether or not this file contains mostly concrete data. Will be used by some SimProcedures to choose how to handle variable-length operations like fgets.
Variables:

has_end – Whether this file has an EOF

category
set_state(state)
size
concretize(**kwargs)

Return a concretization of the contents of the file, as a flat bytestring.

read(pos, size, **kwargs)
write(pos, data, size=None, events=True, **kwargs)
copy(memo=None, **kwargs)
merge(others, merge_conditions, common_ancestor=None)
widen(_)
class angr.storage.file.SimFileStream(name, content=None, pos=0, **kwargs)

Bases: angr.storage.file.SimFile

A specialized SimFile that uses a flat memory backing, but functions as a stream, tracking its position internally.

The pos argument to the read and write methods will be ignored, and will return None. Instead, there is an attribute pos on the file itself, which will give you what you want.

Parameters:
  • name – The name of the file, for cosmetic purposes
  • pos – The initial position of the file, default zero
  • kwargs – Any other keyword arguments will go on to the SimFile constructor.
Variables:

pos – The current position in the file.

set_state(state)
read(pos, size, **kwargs)
write(_, data, size=None, **kwargs)
copy(memo=None, **kwargs)
merge(others, merge_conditions, common_ancestor=None)
class angr.storage.file.SimPackets(name, write_mode=None, content=None, writable=True, ident=None, **kwargs)

Bases: angr.storage.file.SimFileBase

The SimPackets is meant to model inputs whose content is delivered a series of asynchronous chunks. The data is stored as a list of read or write results. For symbolic sizes, state.libc.max_packet_size will be respected. If the SHORT_READS option is enabled, reads will return a symbolic size constrained to be less than or equal to the requested size.

A SimPackets cannot be used for both reading and writing - for socket objects that can be both read and written to you should use a file descriptor to multiplex the read and write operations into two separate file storage mechanisms.

Parameters:
  • name – The name of the file, for cosmetic purposes
  • write_mode – Whether this file is opened in read or write mode. If this is unspecified it will be autodetected.
  • content – Some initial content to use for the file. Can be a list of bytestrings or a list of tuples of content ASTs and size ASTs.
Variables:
  • write_mode – See the eponymous parameter
  • content – A list of packets, as tuples of content ASTs and size ASTs.
size
concretize(**kwargs)

Returns a list of the packets read or written as bytestrings.

read(pos, size, **kwargs)

Read a packet from the stream.

Parameters:
  • pos (int) – The packet number to read from the sequence of the stream. May be None to append to the stream.
  • size – The size to read. May be symbolic.
  • short_reads – Whether to replace the size with a symbolic value constrained to less than or equal to the original size. If unspecified, will be chosen based on the state option.
Returns:

A tuple of the data read (a bitvector of the length that is the maximum length of the read) and the actual size of the read.

write(pos, data, size=None, events=True, **kwargs)

Write a packet to the stream.

Parameters:
  • pos (int) – The packet number to write in the sequence of the stream. May be None to append to the stream.
  • data – The data to write, as a string or bitvector.
  • size – The optional size to write. May be symbolic; must be constrained to at most the size of data.
Returns:

The next packet to use after this

copy(memo=None, **kwargs)
merge(others, merge_conditions, common_ancestor=None)
widen(_)
class angr.storage.file.SimPacketsStream(name, pos=0, **kwargs)

Bases: angr.storage.file.SimPackets

A specialized SimPackets that tracks its position internally.

The pos argument to the read and write methods will be ignored, and will return None. Instead, there is an attribute pos on the file itself, which will give you what you want.

Parameters:
  • name – The name of the file, for cosmetic purposes
  • pos – The initial position of the file, default zero
  • kwargs – Any other keyword arguments will go on to the SimPackets constructor.
Variables:

pos – The current position in the file.

read(_, size, **kwargs)
write(_, data, size=None, **kwargs)
copy(memo=None, **kwargs)
merge(others, merge_conditions, common_ancestor=None)
class angr.storage.file.SimFileDescriptorBase

Bases: angr.state_plugins.plugin.SimStatePlugin

The base class for implementations of POSIX file descriptors.

All file descriptors should respect the CONCRETIZE_SYMBOLIC_{READ,WRITE}_SIZES state options.

read(pos, size, **kwargs)

Reads some data from the file, storing it into memory.

Parameters:
  • pos – The address to write the read data into memory
  • size – The requested length of the read
Returns:

The real length of the read

write(pos, size, **kwargs)

Writes some data, loaded from the state, into the file.

Parameters:
  • pos – The address to read the data to write from in memory
  • size – The requested size of the write
Returns:

The real length of the write

read_data(size, **kwargs)

Reads some data from the file, returning the data.

Parameters:size – The requested length of the read
Returns:A tuple of the data read and the real length of the read
write_data(data, size=None, **kwargs)

Write some data, provided as an argument into the file.

Parameters:
  • data – A bitvector to write into the file
  • size – The requested size of the write (may be symbolic)
Returns:

The real length of the write

seek(offset, whence='start')

Seek the file descriptor to a different position in the file.

Parameters:
  • offset – The offset to seek to, interpreted according to whence
  • whence – What the offset is relative to; one of the strings “start”, “current”, or “end”
Returns:

A symbolic boolean describing whether the seek succeeded or not

tell()

Return the current position, or None if the concept doesn’t make sense for the given file.

eof()

Return the EOF status. May be a symbolic boolean.

size()

Return the size of the data stored in the file in bytes, or None if the concept doesn’t make sense for the given file.

read_storage

Return the SimFile backing reads from this fd

write_storage

Return the SimFile backing writes to this fd

read_pos

Return the current position of the read file pointer.

If the underlying read file is a stream, this will return the position of the stream. Otherwise, will return the position of the file descriptor in the file.

write_pos

Return the current position of the read file pointer.

If the underlying read file is a stream, this will return the position of the stream. Otherwise, will return the position of the file descriptor in the file.

concretize(**kwargs)

Return a concretizeation of the data in the underlying file. Has different return types to represent differnt data structures on a per-class basis.

Any arguments passed to this will be passed onto state.solver.eval.

class angr.storage.file.SimFileDescriptor(simfile, flags=0)

Bases: angr.storage.file.SimFileDescriptorBase

A simple file descriptor forwarding reads and writes to a SimFile. Contains information about the current opened state of the file, such as the flags or (if relevant) the current position.

Variables:
  • file – The SimFile described to by this descriptor
  • flags – The mode that the file descriptor was opened with, a bitfield of flags
read_data(size, **kwargs)
write_data(data, size=None, **kwargs)
seek(offset, whence='start')
eof()
tell()
size()
concretize(**kwargs)

Return a concretization of the underlying file. Returns whatever format is preferred by the file.

read_storage
write_storage
read_pos
write_pos
set_state(state)
copy(memo=None, **kwargs)
merge(others, merge_conditions, common_ancestor=None)
widen(_)
class angr.storage.file.SimFileDescriptorDuplex(read_file, write_file)

Bases: angr.storage.file.SimFileDescriptorBase

A file descriptor that refers to two file storage mechanisms, one to read from and one to write to. As a result, operations like seek, eof, etc no longer make sense.

Parameters:
  • read_file – The SimFile to read from
  • write_file – The SimFile to write to
read_data(size, **kwargs)
write_data(data, size=None, **kwargs)
set_state(state)
eof()
tell()
seek(offset, whence='start')
size()
concretize(**kwargs)

Return a concretization of the underlying files, as a tuple of (read file, write file).

read_storage
write_storage
read_pos
write_pos
copy(memo=None, **kwargs)
merge(others, merge_conditions, common_ancestor=None)
widen(_)
class angr.storage.file.SimPacketsSlots(name, read_sizes, ident=None, **kwargs)

Bases: angr.storage.file.SimFileBase

SimPacketsSlots is the new SimDialogue, if you’ve ever seen that before.

The idea is that in some cases, the only thing you really care about is getting the lengths of reads right, and some of them should be short reads, and some of them should be truncated. You provide to this class a list of read lengths, and it figures out the length of each read, and delivers some content.

This class will NOT respect the position argument you pass it - this storage is not stateless.

seekable = False
concretize(**kwargs)
read(pos, size, **kwargs)
write(pos, data, size=None, **kwargs)
size
copy(memo=None, **kwargs)
merge(others, merge_conditions, common_ancestor=None)
widen(_)
class angr.storage.memory.AddressWrapper(region, region_base_addr, address, is_on_stack, function_address)

Bases: object

AddressWrapper is used in SimAbstractMemory, which provides extra meta information for an address (or a ValueSet object) that is normalized from an integer/BVV/StridedInterval.

Constructor for the class AddressWrapper.

Parameters:
  • strregion – Name of the memory regions it belongs to.
  • region_base_addr (int) – Base address of the memory region
  • address – An address (not a ValueSet object).
  • is_on_stack (bool) – Whether this address is on a stack region or not.
  • function_address (int) – Related function address (if any).
to_valueset(state)

Convert to a ValueSet instance

Parameters:state – A state
Returns:The converted ValueSet instance
class angr.storage.memory.RegionDescriptor(region_id, base_address, related_function_address=None)

Bases: object

Descriptor for a memory region ID.

class angr.storage.memory.RegionMap(is_stack)

Bases: object

Mostly used in SimAbstractMemory, RegionMap stores a series of mappings between concrete memory address ranges and memory regions, like stack frames and heap regions.

Constructor

Parameters:is_stack – Whether this is a region map for stack frames or not. Different strategies apply for stack regions.
is_empty
stack_base
region_ids
copy(memo=None, **kwargs)
map(absolute_address, region_id, related_function_address=None)

Add a mapping between an absolute address and a region ID. If this is a stack region map, all stack regions beyond (lower than) this newly added regions will be discarded.

Parameters:
  • absolute_address – An absolute memory address.
  • region_id – ID of the memory region.
  • related_function_address – A related function address, mostly used for stack regions.
unmap_by_address(absolute_address)

Removes a mapping based on its absolute address.

Parameters:absolute_address – An absolute address
absolutize(region_id, relative_address)

Convert a relative address in some memory region to an absolute address.

Parameters:
  • region_id – The memory region ID
  • relative_address – The relative memory offset in that memory region
Returns:

An absolute address if converted, or an exception is raised when region id does not exist.

relativize(absolute_address, target_region_id=None)

Convert an absolute address to the memory offset in a memory region.

Note that if an address belongs to heap region is passed in to a stack region map, it will be converted to an offset included in the closest stack frame, and vice versa for passing a stack address to a heap region. Therefore you should only pass in address that belongs to the same category (stack or non-stack) of this region map.

Parameters:absolute_address – An absolute memory address
Returns:A tuple of the closest region ID, the relative offset, and the related function address.
class angr.storage.memory.MemoryStoreRequest(addr, data=None, size=None, condition=None, endness=None)

Bases: object

A MemoryStoreRequest is used internally by SimMemory to track memory request data.

class angr.storage.memory.SimMemory(endness=None, abstract_backer=None, stack_region_map=None, generic_region_map=None)

Bases: angr.state_plugins.plugin.SimStatePlugin

Represents the memory space of the process.

category

reg, mem, or file.

Type:Return the category of this SimMemory instance. It can be one of the three following categories
variable_key_prefix
set_state(state)

Call the set_state method in SimStatePlugin class, and then perform the delayed initialization.

Parameters:state – The SimState instance
set_stack_address_mapping(absolute_address, region_id, related_function_address=None)

Create a new mapping between an absolute address (which is the base address of a specific stack frame) and a region ID.

Parameters:
  • absolute_address – The absolute memory address.
  • region_id – The region ID.
  • related_function_address – Related function address.
unset_stack_address_mapping(absolute_address)

Remove a stack mapping.

Parameters:absolute_address – An absolute memory address, which is the base address of the stack frame to destroy.
stack_id(function_address)

Return a memory region ID for a function. If the default region ID exists in the region mapping, an integer will appended to the region name. In this way we can handle recursive function calls, or a function that appears more than once in the call frame.

This also means that stack_id() should only be called when creating a new stack frame for a function. You are not supposed to call this function every time you want to map a function address to a stack ID.

Parameters:function_address (int) – Address of the function.
Returns:ID of the new memory region.
Return type:str
store(addr, data, size=None, condition=None, add_constraints=None, endness=None, action=None, inspect=True, priv=None, disable_actions=False)

Stores content into memory.

Parameters:
  • addr – A claripy expression representing the address to store at.
  • data – The data to store (claripy expression or something convertable to a claripy expression).
  • size – A claripy expression representing the size of the data to store.

The following parameters are optional.

Parameters:
  • condition – A claripy expression representing a condition if the store is conditional.
  • add_constraints – Add constraints resulting from the merge (default: True).
  • endness – The endianness for the data.
  • action – A SimActionData to fill out with the final written value and constraints.
  • inspect (bool) – Whether this store should trigger SimInspect breakpoints or not.
  • disable_actions (bool) – Whether this store should avoid creating SimActions or not. When set to False, state options are respected.
store_cases(addr, contents, conditions, fallback=None, add_constraints=None, endness=None, action=None)

Stores content into memory, conditional by case.

Parameters:
  • addr – A claripy expression representing the address to store at.
  • contents – A list of bitvectors, not necessarily of the same size. Use None to denote an empty write.
  • conditions – A list of conditions. Must be equal in length to contents.

The following parameters are optional.

Parameters:
  • fallback – A claripy expression representing what the write should resolve to if all conditions evaluate to false (default: whatever was there before).
  • add_constraints – Add constraints resulting from the merge (default: True)
  • endness – The endianness for contents as well as fallback.
  • action (SimActionData) – A SimActionData to fill out with the final written value and constraints.
load(addr, size=None, condition=None, fallback=None, add_constraints=None, action=None, endness=None, inspect=True, disable_actions=False, ret_on_segv=False)

Loads size bytes from dst.

Parameters:
  • dst – The address to load from.
  • size – The size (in bytes) of the load.
  • condition – A claripy expression representing a condition for a conditional load.
  • fallback – A fallback value if the condition ends up being False.
  • add_constraints – Add constraints resulting from the merge (default: True).
  • action – A SimActionData to fill out with the constraints.
  • endness – The endness to load with.
  • inspect (bool) – Whether this store should trigger SimInspect breakpoints or not.
  • disable_actions (bool) – Whether this store should avoid creating SimActions or not. When set to False, state options are respected.
  • ret_on_segv (bool) – Whether returns the memory that is already loaded before a segmentation fault is triggered. The default is False.

There are a few possible return values. If no condition or fallback are passed in, then the return is the bytes at the address, in the form of a claripy expression. For example:

<A BVV(0x41, 32)>

On the other hand, if a condition and fallback are provided, the value is conditional:

<A If(condition, BVV(0x41, 32), fallback)>
normalize_address(addr, is_write=False)

Normalize addr for use in static analysis (with the abstract memory model). In non-abstract mode, simply returns the address in a single-element list.

find(addr, what, max_search=None, max_symbolic_bytes=None, default=None, step=1, disable_actions=False, inspect=True)

Returns the address of bytes equal to ‘what’, starting from ‘start’. Note that, if you don’t specify a default value, this search could cause the state to go unsat if no possible matching byte exists.

Parameters:
  • addr – The start address.
  • what – What to search for;
  • max_search – Search at most this many bytes.
  • max_symbolic_bytes – Search through at most this many symbolic bytes.
  • default – The default value, if what you’re looking for wasn’t found.
  • step – The stride that the search should use while scanning memory
  • disable_actions – Whether to inhibit the creation of SimActions for memory access
  • inspect – Whether to trigger SimInspect breakpoints
Returns:

An expression representing the address of the matching byte.

copy_contents(dst, src, size, condition=None, src_memory=None, dst_memory=None, inspect=True, disable_actions=False)

Copies data within a memory.

Parameters:
  • dst – A claripy expression representing the address of the destination
  • src – A claripy expression representing the address of the source

The following parameters are optional.

Parameters:
  • src_memory – Copy data from this SimMemory instead of self
  • src_memory – Copy data to this SimMemory instead of self
  • size – A claripy expression representing the size of the copy
  • condition – A claripy expression representing a condition, if the write should be conditional. If this is determined to be false, the size of the copy will be 0.
class angr.state_plugins.symbolic_memory.MultiwriteAnnotation

Bases: claripy.annotation.Annotation

eliminatable
relocateable
class angr.state_plugins.symbolic_memory.SimSymbolicMemory(memory_backer=None, permissions_backer=None, mem=None, memory_id='mem', endness=None, abstract_backer=False, check_permissions=None, read_strategies=None, write_strategies=None, stack_region_map=None, generic_region_map=None)

Bases: angr.storage.memory.SimMemory

copy(memo=None, **kwargs)
merge(others, merge_conditions, common_ancestor=None)

Merge this SimMemory with the other SimMemory

widen(others)
set_state(state)
make_symbolic(name, addr, length=None)

Replaces length bytes starting at addr with a symbolic variable named name. Adds a constraint equaling that symbolic variable to the value previously at addr, and returns the variable.

concretize_write_addr(addr, strategies=None)

Concretizes an address meant for writing.

param addr:An expression for the address.
param strategies:
 A list of concretization strategies (to override the default).
returns:A list of concrete addresses.
concretize_read_addr(addr, strategies=None)

Concretizes an address meant for reading.

param addr:An expression for the address.
param strategies:
 A list of concretization strategies (to override the default).
returns:A list of concrete addresses.
normalize_address(addr, is_write=False)
was_written_to(dst)
get_unconstrained_bytes(name, bits, source=None, key=None, inspect=True, events=True, **kwargs)

Get some consecutive unconstrained bytes.

Parameters:
  • name – Name of the unconstrained variable
  • bits – Size of the unconstrained variable
  • source – Where those bytes are read from. Currently it is only used in under-constrained symbolic execution so that we can track the allocation depth.
Returns:

The generated variable

unconstrain_byte(addr, inspect=True, events=True)
unconstrain_differences(other)
dbg_print(indent=0)

Print out debugging information.

changed_bytes(other)

Gets the set of changed bytes between self and other.

Parameters:other – The other SimSymbolicMemory.
Returns:A set of differing bytes
replace_all(old, new)

Replaces all instances of expression old with expression new.

Parameters:
  • old – A claripy expression. Must contain at least one named variable (to make to make it possible to use the name index for speedup)
  • new – The new variable to replace it with
addrs_for_name(n)

Returns addresses that contain expressions that contain a variable named n.

addrs_for_hash(h)

Returns addresses that contain expressions that contain a variable with the hash of h.

replace_memory_object(old, new_content)

Replaces the memory object ‘old’ with a new memory object containing ‘new_content’.

Parameters:
  • old – A SimMemoryObject (i.e., one from memory_objects_for_hash() or memory_objects_for_name())
  • new_content – the content (claripy expression) for the new memory object
memory_objects_for_name(n)

Returns a set of SimMemoryObjects that contain expressions that contain a variable with the name of n. This is useful for replacing those values, in one fell swoop, with replace_memory_object(), even if they’ve been partially overwritten.

memory_objects_for_hash(n)

Returns a set of SimMemoryObjects that contain expressions that contain a variable with the hash of h. This is useful for replacing those values, in one fell swoop, with replace_memory_object(), even if they’ve been partially overwritten.

permissions(addr, permissions=None)

Retrieve the permissions of the page at address addr.

Parameters:
  • addr – address to get the page permissions
  • permissions – Integer or BVV to optionally set page permissions to
Returns:

AST representing the permissions on the page

map_region(addr, length, permissions, init_zero=False)

Map a number of pages at address addr with permissions permissions. :param addr: address to map the pages at :param length: length in bytes of region to map, will be rounded upwards to the page size :param permissions: AST of permissions to map, will be a bitvalue representing flags :param init_zero: Initialize page with zeros

unmap_region(addr, length)

Unmap a number of pages at address addr :param addr: address to unmap the pages at :param length: length in bytes of region to map, will be rounded upwards to the page size

class angr.state_plugins.abstract_memory.MemoryRegion(id, state, is_stack=False, related_function_addr=None, init_memory=True, backer_dict=None, endness=None)

Bases: object

id
memory
state
alocs
is_stack
related_function_addr
get_abstract_locations(addr, size)

Get a list of abstract locations that is within the range of [addr, addr + size]

This implementation is pretty slow. But since this method won’t be called frequently, we can live with the bad implementation for now.

Parameters:
  • addr – Starting address of the memory region.
  • size – Size of the memory region, in bytes.
Returns:

A list of covered AbstractLocation objects, or an empty list if there is none.

addrs_for_name(name)
set_state(state)
copy(memo=None, **kwargs)
store(request, bbl_addr, stmt_id, ins_addr)
load(addr, size, bbl_addr, stmt_idx, ins_addr)
merge(others, merge_conditions, common_ancestor=None)
widen(others)
was_written_to(addr)
dbg_print(indent=0)

Print out debugging information

class angr.state_plugins.abstract_memory.SimAbstractMemory(memory_backer=None, memory_id='mem', endness=None, stack_region_map=None, generic_region_map=None)

Bases: angr.storage.memory.SimMemory

This is an implementation of the abstract store in paper [TODO].

Some differences:

  • For stack variables, we map the absolute stack address to each region so that we can effectively trace stack accesses. When tracing into a new function, you should call set_stack_address_mapping() to create a new mapping. When exiting from a function, you should cancel the previous mapping by calling unset_stack_address_mapping(). Currently this is only used for stack!
regions
set_stack_size(size)
create_region(key, state, is_stack, related_function_addr, endness, backer_dict=None)

Create a new MemoryRegion with the region key specified, and store it to self._regions.

Parameters:
  • key – a string which is the region key
  • state – the SimState instance
  • is_stack (bool) – Whether this memory region is on stack. True/False
  • related_function_addr – Which function first creates this memory region. Just for reference.
  • endness – The endianness.
  • backer_dict – The memory backer object.
Returns:

None

set_state(state)

Overriding the SimStatePlugin.set_state() method

Parameters:state – A SimState object
Returns:None
normalize_address(addr, is_write=False, convert_to_valueset=False, target_region=None, condition=None)

Convert a ValueSet object into a list of addresses.

Parameters:
  • addr – A ValueSet object (which describes an address)
  • is_write – Is this address used in a write or not
  • convert_to_valueset – True if you want to have a list of ValueSet instances instead of AddressWrappers, False otherwise
  • target_region – Which region to normalize the address to. To leave the decision to SimuVEX, set it to None
Returns:

A list of AddressWrapper or ValueSet objects

find(addr, what, max_search=None, max_symbolic_bytes=None, default=None, step=1)
get_segments(addr, size)

Get a segmented memory region based on AbstractLocation information available from VSA.

Here are some assumptions to make this method fast:
  • The entire memory region [addr, addr + size] is located within the same MemoryRegion
  • The address ‘addr’ has only one concrete value. It cannot be concretized to multiple values.
Parameters:
  • addr – An address
  • size – Size of the memory area in bytes
Returns:

An ordered list of sizes each segment in the requested memory region

copy(memo=None, **kwargs)
merge(others, merge_conditions, common_ancestor=None)

Merge this guy with another SimAbstractMemory instance

widen(others)
map_region(addr, length, permissions, init_zero=False)

Map a number of pages at address addr with permissions permissions. :param addr: address to map the pages at :param length: length in bytes of region to map, will be rounded upwards to the page size :param permissions: AST of permissions to map, will be a bitvalue representing flags :param init_zero: Initialize page with zeros

unmap_region(addr, length)

Unmap a number of pages at address addr :param addr: address to unmap the pages at :param length: length in bytes of region to map, will be rounded upwards to the page size

was_written_to(dst)
dbg_print()

Print out debugging information

class angr.storage.memory_object.SimMemoryObject(obj, base, length=None, byte_width=8)

Bases: object

A MemoryObjectRef instance is a reference to a byte or several bytes in a specific object in SimSymbolicMemory. It is only used inside SimSymbolicMemory class.

size()
last_addr
includes(x)
bytes_at(addr, length)
class angr.storage.pcap.PCAP(path, ip_port_tup, init=True)

Bases: object

initialize(path)
recv(length)
copy()
class angr.storage.paged_memory.BasePage(page_addr, page_size, permissions=None, executable=False)

Bases: object

Page object, allowing for more flexibility than just a raw dict.

Create a new page object. Carries permissions information. Permissions default to RW unless executable is True, in which case permissions default to RWX.

Parameters:
  • page_addr (int) – The base address of the page.
  • page_size (int) – The size of the page.
  • executable (bool) – Whether the page is executable. Typically, this will depend on whether the binary has an executable stack.
  • permissions (claripy.AST) – A 3-bit bitvector setting specific permissions for EXEC, READ, and WRITE
PROT_READ = 1
PROT_WRITE = 2
PROT_EXEC = 4
concrete_permissions
contains(state, idx)
store_mo(state, new_mo, overwrite=True)

Stores a memory object.

Parameters:
  • new_mo – the memory object
  • overwrite – whether to overwrite objects already in memory (if false, just fill in the holes)
copy()
load_mo(state, page_idx)

Loads a memory object from memory.

Parameters:page_idx – the index into the page
Returns:a tuple of the object
keys()
replace_mo(state, old_mo, new_mo)
store_overwrite(state, new_mo, start, end)
store_underwrite(state, new_mo, start, end)
load_slice(state, start, end)

Return the memory objects overlapping with the provided slice.

Parameters:
  • start – the start address
  • end – the end address (non-inclusive)
Returns:

tuples of (starting_addr, memory_object)

class angr.storage.paged_memory.TreePage(*args, **kwargs)

Bases: angr.storage.paged_memory.BasePage

Page object, implemented with a sorted dict. Who knows what’s underneath!

keys()
replace_mo(state, old_mo, new_mo)
store_overwrite(state, new_mo, start, end)
store_underwrite(state, new_mo, start, end)
load_mo(state, page_idx)

Loads a memory object from memory.

Parameters:page_idx – the index into the page
Returns:a tuple of the object
load_slice(state, start, end)

Return the memory objects overlapping with the provided slice.

Parameters:
  • start – the start address
  • end – the end address (non-inclusive)
Returns:

tuples of (starting_addr, memory_object)

class angr.storage.paged_memory.ListPage(*args, **kwargs)

Bases: angr.storage.paged_memory.BasePage

Page object, implemented with a list.

keys()
replace_mo(state, old_mo, new_mo)
store_overwrite(state, new_mo, start, end)
store_underwrite(state, new_mo, start, end)
load_mo(state, page_idx)

Loads a memory object from memory.

Parameters:page_idx – the index into the page
Returns:a tuple of the object
load_slice(state, start, end)

Return the memory objects overlapping with the provided slice.

Parameters:
  • start – the start address
  • end – the end address (non-inclusive)
Returns:

tuples of (starting_addr, memory_object)

angr.storage.paged_memory.Page

alias of angr.storage.paged_memory.ListPage

class angr.storage.paged_memory.SimPagedMemory(memory_backer=None, permissions_backer=None, pages=None, initialized=None, name_mapping=None, hash_mapping=None, page_size=None, symbolic_addrs=None, check_permissions=False)

Bases: object

Represents paged memory.

branch()
allow_segv
byte_width
load_objects(addr, num_bytes, ret_on_segv=False)

Load memory objects from paged memory.

Parameters:
  • addr – Address to start loading.
  • num_bytes – Number of bytes to load.
  • ret_on_segv (bool) – True if you want load_bytes to return directly when a SIGSEV is triggered, otherwise a SimSegfaultError will be raised.
Returns:

list of tuples of (addr, memory_object)

Return type:

tuple

contains_no_backer(addr)

Tests if the address is contained in any page of paged memory, without considering memory backers.

Parameters:addr (int) – The address to test.
Returns:True if the address is included in one of the pages, False otherwise.
Return type:bool
keys()
changed_bytes(other)
store_memory_object(mo, overwrite=True)

This function optimizes a large store by storing a single reference to the SimMemoryObject instead of one for each byte.

Parameters:memory_object – the memory object to store
replace_memory_object(old, new_content)

Replaces the memory object old with a new memory object containing new_content.

Parameters:
  • old – A SimMemoryObject (i.e., one from memory_objects_for_hash() or :func:` memory_objects_for_name()`).
  • new_content – The content (claripy expression) for the new memory object.
Returns:

the new memory object

replace_all(old, new)

Replaces all instances of expression old with expression new.

Parameters:
  • old – A claripy expression. Must contain at least one named variable (to make it possible to use the name index for speedup).
  • new – The new variable to replace it with.
get_symbolic_addrs()
addrs_for_name(n)

Returns addresses that contain expressions that contain a variable named n.

addrs_for_hash(h)

Returns addresses that contain expressions that contain a variable with the hash of h.

memory_objects_for_name(n)

Returns a set of SimMemoryObjects that contain expressions that contain a variable with the name of n.

This is useful for replacing those values in one fell swoop with replace_memory_object(), even if they have been partially overwritten.

memory_objects_for_hash(n)

Returns a set of SimMemoryObjects that contain expressions that contain a variable with the hash h.

permissions(addr, permissions=None)

Returns the permissions for a page at address addr.

If optional argument permissions is given, set page permissions to that prior to returning permissions.

map_region(addr, length, permissions, init_zero=False)
unmap_region(addr, length)
class angr.concretization_strategies.SimConcretizationStrategy(filter=None, exact=True)

Bases: object

Concretization strategies control the resolution of symbolic memory indices in SimuVEX. By subclassing this class and setting it as a concretization strategy (on state.memory.read_strategies and state.memory.write_strategies), SimuVEX’s memory index concretization behavior can be modified.

Initializes the base SimConcretizationStrategy.

Parameters:
  • filter – A function, taking arguments of (SimMemory, claripy.AST) that determins if this strategy can handle resolving the provided AST.
  • exact – A flag (default: True) that determines if the convenience resolution functions provided by this class use exact or approximate resolution.
concretize(memory, addr)

Concretizes the address into a list of values. If this strategy cannot handle this address, returns None.

copy()

Returns a copy of the strategy, if there is data that should be kept separate between states. If not, returns self.

merge(others)

Merges this strategy with others (if there is data that should be kept separate between states. If not, is a no-op.

Concretization Strategies

class angr.concretization_strategies.single.SimConcretizationStrategySingle(filter=None, exact=True)

Bases: angr.concretization_strategies.SimConcretizationStrategy

Concretization strategy that ensures a single solution for an address.

Initializes the base SimConcretizationStrategy.

Parameters:
  • filter – A function, taking arguments of (SimMemory, claripy.AST) that determins if this strategy can handle resolving the provided AST.
  • exact – A flag (default: True) that determines if the convenience resolution functions provided by this class use exact or approximate resolution.
class angr.concretization_strategies.eval.SimConcretizationStrategyEval(limit, **kwargs)

Bases: angr.concretization_strategies.SimConcretizationStrategy

Concretization strategy that resolves an address into some limited number of solutions. Always handles the concretization, but only returns a maximum of limit number of solutions. Therefore, should only be used as the fallback strategy.

class angr.concretization_strategies.norepeats.SimConcretizationStrategyNorepeats(repeat_expr, repeat_constraints=None, **kwargs)

Bases: angr.concretization_strategies.SimConcretizationStrategy

Concretization strategy that resolves addresses, without repeating.

copy()
merge(others)
class angr.concretization_strategies.solutions.SimConcretizationStrategySolutions(limit, **kwargs)

Bases: angr.concretization_strategies.SimConcretizationStrategy

Concretization strategy that resolves an address into some limited number of solutions.

class angr.concretization_strategies.nonzero_range.SimConcretizationStrategyNonzeroRange(limit, **kwargs)

Bases: angr.concretization_strategies.SimConcretizationStrategy

Concretization strategy that resolves a range in a non-zero location.

class angr.concretization_strategies.range.SimConcretizationStrategyRange(limit, **kwargs)

Bases: angr.concretization_strategies.SimConcretizationStrategy

Concretization strategy that resolves addresses to a range.

class angr.concretization_strategies.max.SimConcretizationStrategyMax(filter=None, exact=True)

Bases: angr.concretization_strategies.SimConcretizationStrategy

Concretization strategy that returns the maximum address.

Initializes the base SimConcretizationStrategy.

Parameters:
  • filter – A function, taking arguments of (SimMemory, claripy.AST) that determins if this strategy can handle resolving the provided AST.
  • exact – A flag (default: True) that determines if the convenience resolution functions provided by this class use exact or approximate resolution.
class angr.concretization_strategies.norepeats_range.SimConcretizationStrategyNorepeatsRange(repeat_expr, min=None, granularity=None, **kwargs)

Bases: angr.concretization_strategies.SimConcretizationStrategy

Concretization strategy that resolves a range, with no repeats.

copy()
merge(others)
class angr.concretization_strategies.nonzero.SimConcretizationStrategyNonzero(filter=None, exact=True)

Bases: angr.concretization_strategies.SimConcretizationStrategy

Concretization strategy that returns any non-zero solution.

Initializes the base SimConcretizationStrategy.

Parameters:
  • filter – A function, taking arguments of (SimMemory, claripy.AST) that determins if this strategy can handle resolving the provided AST.
  • exact – A flag (default: True) that determines if the convenience resolution functions provided by this class use exact or approximate resolution.
class angr.concretization_strategies.any.SimConcretizationStrategyAny(filter=None, exact=True)

Bases: angr.concretization_strategies.SimConcretizationStrategy

Concretization strategy that returns any single solution.

Initializes the base SimConcretizationStrategy.

Parameters:
  • filter – A function, taking arguments of (SimMemory, claripy.AST) that determins if this strategy can handle resolving the provided AST.
  • exact – A flag (default: True) that determines if the convenience resolution functions provided by this class use exact or approximate resolution.
class angr.concretization_strategies.controlled_data.SimConcretizationStrategyControlledData(limit, fixed_addrs, **kwargs)

Bases: angr.concretization_strategies.SimConcretizationStrategy

Concretization strategy that constraints the address to controlled data. Controlled data consists of symbolic data and the addresses given as arguments. memory.

Simulation Manager

class angr.sim_manager.SimulationManager(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, **kwargs)

Bases: ana.storable.Storable

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.
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'
errored
stashes
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.

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, **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', n=None, selector_func=None, step_func=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’)
  • 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, **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.
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')

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 aproximation. By default: uses PC, callstack, and open file descriptors.
Returns:

The simulation manager, for chaining.

Return type:

SimulationManager

class angr.sim_manager.ErrorRecord(state, error, traceback)

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 – The state that encountered an error, at the point in time just before the erroring step began.
  • error – The error that was thrown.
  • traceback – The traceback for the error that was thrown.
debug()

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

reraise()
class angr.state_hierarchy.StateHierarchy

Bases: object

get_ref(obj)
clear_ref(ref)
add_state(s)
add_history(h)
simplify()
full_simplify()
lineage(h)

Returns the lineage of histories leading up to h.

all_successors(h)
history_successors(h)
history_predecessors(h)
history_contains(h)
unreachable_state(state)
unreachable_history(h)
most_mergeable(states)

Find the “most mergeable” set of states from those provided.

Parameters:states – a list of states
Returns:a tuple of: (a list of states to merge, those states’ common history, a list of states to not merge yet)

Exploration Techniques

class angr.exploration_techniques.ExplorationTechniqueMeta

Bases: type

class angr.exploration_techniques.ExplorationTechnique

Bases: object

An otiegnqwvk is a set of hooks for a simulation manager that assists in the implementation of new techniques in symbolic exploration.

TODO: choose actual name for the functionality (techniques? strategies?)

Any number of these methods may be overridden by a subclass. To use an exploration technique, call simgr.use_technique with an instance of the technique.

Warning

There is currently installed a compatibility layer for the previous version of this API. This layer requires that implementations of ExplorationTechnique use the same argument names as the original methods, or else it will mangle the behvior.

setup(simgr)

Perform any initialization on this manager you might need to do.

Parameters:simgr (angr.SimulationManager) – The simulation manager to which you have just been added
step(simgr, stash='active', **kwargs)

Hook the process of stepping a stash forward. Should call simgr.step(stash, **kwargs) in order to do the actual processing.

Parameters:
  • simgr (angr.SimulationManager) –
  • stash (str) –
filter(simgr, state, **kwargs)

Perform filtering on which stash a state should be inserted into.

If the state should be filtered, return the name of the stash to move the state to. If you want to modify the state before filtering it, return a tuple of the stash to move the state to and the modified state. To defer to the original categorization procedure, return the result of simgr.filter(state, **kwargs)

If the user provided a filter_func in their step or run command, it will appear here.

Parameters:
  • simgr (angr.SimulationManager) –
  • state (angr.SimState) –
selector(simgr, state, **kwargs)

Determine if a state should participate in the current round of stepping. Return True if the state should be stepped, and False if the state should not be stepped. To defer to the original selection procedure, return the result of simgr.selector(state, **kwargs).

If the user provided a selector_func in their step or run command, it will appear here.

Parameters:
  • simgr (angr.SimulationManager) –
  • state (angr.SimState) –
step_state(simgr, state, **kwargs)

Determine the categorization of state successors into stashes. The result should be a dict mapping stash names to the list of successor states that fall into that stash, or None as a stash name to use the original stash name.

If you would like to directly work with a SimSuccessors object, you can obtain it with simgr.successors(state, **kwargs). This is not recommended, as it denies other hooks the opportunity to look at the successors. Therefore, the usual technique is to call simgr.step_state(state, **kwargs) and then mutate the returned dict before returning it yourself.

..note:: This takes precedence over the filter hook - filter is only applied to states returned from here in the None stash.

Parameters:
  • simgr (angr.SimulationManager) –
  • state (angr.SimState) –
successors(simgr, state, **kwargs)

Perform the process of stepping a state forward, returning a SimSuccessors object.

To defer to the original succession procedure, return the result of simgr.successors(state, **kwargs). Be careful about not calling this method (e.g. calling project.factory.successors manually) as it denies other hooks the opportunity to instrument the step. Instead, you can mutate the kwargs for the step before calling the original, and mutate the result before returning it yourself.

If the user provided a successor_func in their step or run command, it will appear here.

Parameters:
  • simgr (angr.SimulationManager) –
  • state (angr.SimState) –
complete(simgr)

Return whether or not this manager has reached a “completed” state, i.e. SimulationManager.run() should halt.

This is the one hook which is not subject to the nesting rules of hooks. You should not call simgr.complete, you should make your own decision and return True or False. Each of the techniques’ completion checkers will be called and the final result will be compted with simgr.completion_mode.

Parameters:simgr (angr.SimulationManager) –
class angr.exploration_techniques.dfs.DFS(deferred_stash='deferred')

Bases: angr.exploration_techniques.ExplorationTechnique

Depth-first search.

Will only keep one path active at a time, any others will be stashed in the ‘deferred’ stash. When we run out of active paths to step, we take the longest one from deferred and continue.

setup(simgr)
step(simgr, stash='active', **kwargs)
class angr.exploration_techniques.explorer.Explorer(find=None, avoid=None, find_stash='found', avoid_stash='avoid', cfg=None, num_find=1, avoid_priority=False)

Bases: angr.exploration_techniques.ExplorationTechnique

Search for up to “num_find” paths that satisfy condition “find”, avoiding condition “avoid”. Stashes found paths into “find_stash’ and avoided paths 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 path 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 paths which cannot possibly reach a success state without going through a failure state will be preemptively avoided.

If either the “find” or “avoid” parameter is a function returning a boolean, and a path triggers both conditions, it will be added to the find stash, unless “avoid_priority” is set to True.

setup(simgr)
step(simgr, stash='active', **kwargs)
filter(simgr, state, **kwargs)
complete(simgr)
class angr.exploration_techniques.lengthlimiter.LengthLimiter(max_length, drop=False)

Bases: angr.exploration_techniques.ExplorationTechnique

Length limiter on paths.

step(simgr, stash='active', **kwargs)
class angr.exploration_techniques.manual_mergepoint.ManualMergepoint(address, wait_counter=10)

Bases: angr.exploration_techniques.ExplorationTechnique

setup(simgr)
filter(simgr, state)
mark_nofilter(simgr, stash)
mark_okfilter(simgr, stash)
step(simgr, stash='active', **kwargs)
class angr.exploration_techniques.spiller.SpilledState(state)

Bases: ana.storable.Storable

class angr.exploration_techniques.spiller.Spiller(src_stash='active', min=5, max=10, staging_stash='spill_stage', staging_min=10, staging_max=20, pickle_callback=None, unpickle_callback=None, priority_key=None)

Bases: angr.exploration_techniques.ExplorationTechnique

Automatically spill states out. It can spill out states to a different stash, spill them out to ANA, or first do the former and then (after enough states) the latter.

Initializes the spiller.

@param max: the number of states that are not spilled @param src_stash: the stash from which to spill states (default: active) @param staging_stash: the stash to which to spill states (default: “spill_stage”) @param staging_max: the number of states that can be in the staging stash before things get spilled to ANA (default: None. If staging_stash is set, then this means unlimited, and ANA will not be used). @param priority_key: a function that takes a state and returns its numberical priority (MAX_INT is lowest priority). By default, self.state_priority will be used, which prioritizes by object ID.

step(simgr, stash='active', **kwargs)
static state_priority(state)
class angr.exploration_techniques.threading.Threading(threads=8)

Bases: angr.exploration_techniques.ExplorationTechnique

Enable multithreading.

This is only useful in paths where a lot of time is taken inside z3, doing constraint solving. This is because of python’s GIL, which says that only one thread at a time may be executing python code.

step(simgr, stash='active', **kwargs)
class angr.exploration_techniques.veritesting.Veritesting(**options)

Bases: angr.exploration_techniques.ExplorationTechnique

Enable veritesting. This technique, described in a paper[1] from CMU, attempts to address the problem of state explosions in loops by performing smart merging.

[1] https://users.ece.cmu.edu/~aavgerin/papers/veritesting-icse-2014.pdf

step_state(simgr, state, successor_func=None, **kwargs)
class angr.exploration_techniques.tracer.Tracer(trace=None, resiliency=False, keep_predecessors=1, crash_addr=None)

Bases: angr.exploration_techniques.ExplorationTechnique

An exploration technique that follows an angr path with a concrete input. The tracing result is the state at the last address of the trace, which can be found in the ‘traced’ stash.

If the given concrete input makes the program crash, you should provide crash_addr, and the crashing state will be found in the ‘crashed’ stash.

Parameters:
  • trace – The basic block trace.
  • resiliency – Should we continue to step forward even if qemu and angr disagree?
  • keep_predecessors – Number of states before the final state we should log.
  • crash_addr – If the trace resulted in a crash, provide the crashing instruction pointer here, and the ‘crashed’ stash will be populated with the crashing state.
Variables:

predecessors – A list of states in the history before the final state.

setup(simgr)
complete(simgr)
filter(simgr, state, **kwargs)
step(simgr, stash='active', **kwargs)
step_state(simgr, state, **kwargs)
class angr.exploration_techniques.driller_core.DrillerCore(trace, fuzz_bitmap=None)

Bases: angr.exploration_techniques.ExplorationTechnique

An exploration technique that symbolically follows an input looking for new state transitions.

It has to be used with Tracer exploration technique. Results are put in ‘diverted’ stash.

:param trace : The basic block trace. :param fuzz_bitmap: AFL’s bitmap of state transitions. Defaults to saying every transition is worth satisfying.

setup(simgr)
step(simgr, stash='active', **kwargs)
class angr.exploration_techniques.slicecutor.Slicecutor(annotated_cfg, force_taking_exit=False)

Bases: angr.exploration_techniques.ExplorationTechnique

The Slicecutor is an exploration that executes provided code slices.

All parameters except annotated_cfg are optional.

Parameters:
  • annotated_cfg – The AnnotatedCFG that provides the code slice.
  • force_taking_exit – Set to True if you want to create a successor based on our slice in case of unconstrained successors.
setup(simgr)
filter(simgr, state, **kwargs)
step_state(simgr, state, **kwargs)
successors(simgr, state, **kwargs)
class angr.exploration_techniques.director.BaseGoal(sort)

Bases: object

REQUIRE_CFG_STATES = False
check(cfg, state, peek_blocks)
Parameters:
  • cfg (angr.analyses.CFGEmulated) – An instance of CFGEmulated.
  • state (angr.SimState) – The state to check.
  • peek_blocks (int) – Number of blocks to peek ahead from the current point.
Returns:

True if we can determine that this condition is definitely satisfiable if the path is taken, False otherwise.

Return type:

bool

check_state(state)

Check if the current state satisfies the goal.

Parameters:state (angr.SimState) – The state to check.
Returns:True if it satisfies the goal, False otherwise.
Return type:bool
class angr.exploration_techniques.director.ExecuteAddressGoal(addr)

Bases: angr.exploration_techniques.director.BaseGoal

A goal that prioritizes states reaching (or are likely to reach) certain address in some specific steps.

check(cfg, state, peek_blocks)

Check if the specified address will be executed

Parameters:
  • cfg
  • state
  • peek_blocks (int) –
Returns:

Return type:

bool

check_state(state)

Check if the current address is the target address.

Parameters:state (angr.SimState) – The state to check.
Returns:True if the current address is the target address, False otherwise.
Return type:bool
class angr.exploration_techniques.director.CallFunctionGoal(function, arguments)

Bases: angr.exploration_techniques.director.BaseGoal

A goal that prioritizes states reaching certain function, and optionally with specific arguments. Note that constraints on arguments (and on function address as well) have to be identifiable on an accurate CFG. For example, you may have a CallFunctionGoal saying “call printf with the first argument being ‘Hello, world’”, and CFGEmulated must be able to figure our the first argument to printf is in fact “Hello, world”, not some symbolic strings that will be constrained to “Hello, world” during symbolic execution (or simulation, however you put it).

REQUIRE_CFG_STATES = True
check(cfg, state, peek_blocks)

Check if the specified function will be reached with certain arguments.

Parameters:
  • cfg
  • state
  • peek_blocks
Returns:

check_state(state)

Check if the specific function is reached with certain arguments

Parameters:state (angr.SimState) – The state to check
Returns:True if the function is reached with certain arguments, False otherwise.
Return type:bool
class angr.exploration_techniques.director.Director(peek_blocks=100, peek_functions=5, goals=None, cfg_keep_states=False, goal_satisfied_callback=None, num_fallback_states=5)

Bases: angr.exploration_techniques.ExplorationTechnique

An exploration technique for directed symbolic execution.

A control flow graph (using CFGEmulated) is built and refined during symbolic execution. Each time the execution reaches a block that is outside of the CFG, the CFG recovery will be triggered with that state, with a maximum recovery depth (100 by default). If we see a basic block during state stepping that is not yet in the control flow graph, we go back to control flow graph recovery and “peek” more blocks forward.

When stepping a simulation manager, all states are categorized into three different categories:

  • Might reach the destination within the peek depth. Those states are prioritized.
  • Will not reach the destination within the peek depth. Those states are de-prioritized. However, there is a little chance for those states to be explored as well in order to prevent over-fitting.

Constructor.

step(simgr, stash='active', **kwargs)
Parameters:
  • simgr
  • stash
  • kwargs
Returns:

add_goal(goal)

Add a goal.

Parameters:goal (BaseGoal) – The goal to add.
Returns:None
class angr.exploration_techniques.oppologist.Oppologist

Bases: angr.exploration_techniques.ExplorationTechnique

The Oppologist is an exploration technique that forces uncooperative code through qemu.

successors(simgr, state, **kwargs)
class angr.exploration_techniques.loop_seer.LoopSeer(cfg=None, functions=None, loops=None, use_header=False, bound=None, bound_reached=None, discard_stash='spinning')

Bases: angr.exploration_techniques.ExplorationTechnique

This exploration technique monitors exploration and maintains all loop-related data (well, currently it is just the loop trip counts, but feel free to add something else).

Parameters:
  • cfg – Normalized CFG is required.
  • functions – Function(s) containing the loop(s) to be analyzed.
  • loops – Loop(s) to be analyzed.
  • use_header – Whether to use header based trip counter to compare with the bound limit.
  • bound – Limit the number of iteration a loop may be executed.
  • bound_reached – If provided, should be a function that takes a SimulationManager and returns a SimulationManager. Will be called when loop execution reach the given bound. Default to moving states that exceed the loop limit to a discard stash.
  • discard_stash – Name of the stash containing states exceeding the loop limit.
setup(simgr)
step(simgr, stash='active', **kwargs)
successors(simgr, state, **kwargs)
class angr.exploration_techniques.cacher.Cacher(when=None, dump_cache=True, load_cache=True, container=None, lookup=None, dump_func=None, load_func=None)

Bases: angr.exploration_techniques.ExplorationTechnique

An exploration technique that caches states during symbolic execution.

DO NOT USE THIS - THIS IS FOR ARCHIVAL PURPOSES ONLY

Parameters:
  • dump_cache – Whether to dump data to cache.
  • load_cache – Whether to load data from cache.
  • container – Data container.
  • when – If provided, should be a function that takes a SimulationManager and returns a Boolean, or the address of the state to be cached.
  • lookup – A function that returns True if cache hit and False otherwise.
  • dump_func – If provided, should be a function that defines how Cacher should cache the SimulationManager. Default to caching the active stash.
  • load_func – If provided, should be a function that defines how Cacher should uncache the SimulationManager. Default to uncaching the stash to be stepped.
setup(simgr)
step(simgr, stash='active', **kwargs)
class angr.exploration_techniques.stochastic.StochasticSearch(start_state, restart_prob=0.0001)

Bases: angr.exploration_techniques.ExplorationTechnique

Stochastic Search.

Will only keep one path active at a time, any others will be discarded. Before each pass through, weights are randomly assigned to each basic block. These weights form a probability distribution for determining which state remains after splits. When we run out of active paths to step, we start again from the start state.

Parameters:
  • start_state – The initial state from which exploration stems.
  • restart_prob – The probability of randomly restarting the search (default 0.0001).
step(simgr, stash='active', **kwargs)
class angr.exploration_techniques.unique.UniqueSearch(similarity_func=None, deferred_stash='deferred')

Bases: angr.exploration_techniques.ExplorationTechnique

Unique Search.

Will only keep one path active at a time, any others will be deferred. The state that is explored depends on how unique it is relative to the other deferred states. A path’s uniqueness is determined by its average similarity between the other (deferred) paths. Similarity is calculated based on the supplied similarity_func, which by default is: The (L2) distance between the counts of the state addresses in the history of the path.

Parameters:
  • similarity_func – How to calculate similarity between two states.
  • deferred_stash – Where to store the deferred states.
setup(simgr)
step(simgr, stash='active', **kwargs)
static similarity(state_a, state_b)

The (L2) distance between the counts of the state addresses in the history of the path. :param state_a: The first state to compare :param state_b: The second state to compare

static sequence_matcher_similarity(state_a, state_b)

The difflib.SequenceMatcher ratio between the state addresses in the history of the path. :param state_a: The first state to compare :param state_b: The second state to compare

class angr.exploration_techniques.tech_builder.TechniqueBuilder(setup=None, step_state=None, step=None, successors=None, filter=None, selector=None, complete=None)

Bases: angr.exploration_techniques.ExplorationTechnique

This meta technique could be used to hook a couple of simulation manager methods without actually creating a new exploration technique, for example:

class SomeComplexAnalysis(Analysis):

def do_something():
simgr = self.project.factory.simulation_manager() simgr.use_tech(ProxyTechnique(step_state=self._step_state)) simgr.run()
def _step_state(self, state):
# Do stuff! pass

In the above example, the _step_state method can access all the neccessary stuff, hidden in the analysis instance, without passing that instance to a one-shot-styled exploration technique.

angr.exploration_techniques.common.condition_to_lambda(condition, default=False)

Translates an integer, set, list or function into a lambda that checks if state’s current basic block matches some condition.

Parameters:
  • condition – An integer, set, list or lambda to convert to a lambda.
  • default – The default return value of the lambda (in case condition is None). Default: false.
Returns:

A tuple of two items: a lambda that takes a state and returns the set of addresses that it matched from the condition, and a set that contains the normalized set of addresses to stop at, or None if no addresses were provided statically.

Simulation Engines

class angr.engines.engine.SimEngine(project=None)

Bases: object

A SimEngine is a class which understands how to perform execution on a state. This is a base class.

process(state, *args, **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 – 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
Returns:

A SimSuccessors object categorizing the execution’s successor states

check(state, *args, **kwargs)

Check if this engine can be used for execution on the current state. A callback check_failure is called upon failed checks. Note that the execution can still fail even if check() returns True.

You should only override this method in a subclass in order to provide the correct method signature and docstring. You should override the _check method to do your actual execution.

Parameters:
  • state (SimState) – The state with which to execute.
  • args – Positional arguments that will be passed to process().
  • kwargs – Keyword arguments that will be passed to process().
Returns:

True if the state can be handled by the current engine, False otherwise.

class angr.engines.successors.SimSuccessors(addr, initial_state)

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 – 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 – The “normal” successors. IP may be symbolic, but must have reasonable number of solutions
  • unsat_successors – Any successor which is unsatisfiable after its guard condition is added.
  • all_successors – successors + unsat_successors
  • flat_successors – 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 – 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/docs/simuvex.html

classmethod failure()
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).
class angr.engines.hub.EngineHub(project)

Bases: angr.misc.plugins.PluginHub

use_plugin_preset(preset, adjust_order=True)
order
default_engine
has_default_engine()
procedure_engine
has_procedure_engine()
successors(state, addr=None, jumpkind=None, default_engine=False, procedure_engine=False, engines=None, **kwargs)

Perform execution using any applicable engine. Enumerate the current engines and use the first one that works. Engines are enumerated in order, specified by the order attribute.

Parameters:
  • state – The state to analyze
  • addr – optional, an address to execute at instead of the state’s ip
  • jumpkind – optional, the jumpkind of the previous exit
  • default_engine – Whether we should only attempt to use the default engine (usually VEX)
  • procedure_engine – Whether we should only attempt to use the procedure engine
  • engines – A list of engines to try to use, instead of the default. This list is expected to contain engine names or engine instances.

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

Return SimSuccessors:
 A SimSuccessors object classifying the results of the run.
class angr.engines.hub.EnginePreset(predefined_order=None)

Bases: angr.misc.plugins.PluginPreset

This represents a preset of engines for an engine hub.

As was pointed out by @rhelmot (see https://github.com/angr/angr/pull/897), there’s a lot of behavior in angr which very very specifically assumes that failure/syscall/hook will happen exactly the way we want them to. This plugin preset addresses the issue by allowing a user to specify a list of plugins that should be executed first using the predefined_order parameter. In that case, any other adjustment to order will be made with respect to the specified predefined order.

If you want to use your custom preset with the angr’s original analyses, you should specify the following predefined order: failure, syscall, and then hook.

activate(hub)
order
has_order()
default_engine
has_default_engine()
procedure_engine
has_procedure_engine()
copy()
angr.engines.vex.translate_irconst(state, c)
class angr.engines.vex.engine.SimEngineVEX(project=None, stop_points=None, use_cache=None, cache_size=50000, default_opt_level=1, support_selfmodifying_code=None, single_step=False, default_strict_block_end=False)

Bases: angr.engines.engine.SimEngine

Execution engine based on VEX, Valgrind’s IR.

is_stop_point(addr)
process(state, irsb=None, skip_stmts=0, last_stmt=99999999, whitelist=None, inline=False, force_addr=None, insn_bytes=None, size=None, num_inst=None, traceflags=0, thumb=False, opt_level=None, **kwargs)
Parameters:
  • state – The state with which to execute
  • irsb – The PyVEX IRSB object to use for execution. If not provided one will be lifted.
  • skip_stmts – The number of statements to skip in processing
  • last_stmt – Do not execute any statements after this statement
  • whitelist – Only execute statements in this set
  • 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
  • thumb – Whether the block should be lifted in ARM’s THUMB mode.
  • 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:

A SimSuccessors object categorizing the block’s successors

lift(state=None, clemory=None, insn_bytes=None, arch=None, addr=None, size=None, num_inst=None, traceflags=0, thumb=False, opt_level=None, strict_block_end=None, skip_stmts=False, collect_data_refs=False)

Lift an IRSB.

There are many possible valid sets of parameters. You at the very least must pass some source of data, some source of an architecture, and some source of an address.

Sources of data in order of priority: insn_bytes, clemory, state

Sources of an address, in order of priority: addr, state

Sources of an architecture, in order of priority: arch, clemory, state

Parameters:
  • state – A state to use as a data source.
  • clemory – A cle.memory.Clemory object to use as a data source.
  • addr – The address at which to start the block.
  • thumb – Whether the block should be lifted in ARM’s THUMB mode.
  • opt_level – The VEX optimization level to use. The final IR optimization level is determined by (ordered by priority): - Argument opt_level - opt_level is set to 1 if OPTIMIZE_IR exists in state options - self._default_opt_level
  • insn_bytes – A string of bytes to use as a data source.
  • 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)
  • strict_block_end – Whether to force blocks to end at all conditional branches (default: false)
clear_cache()
class angr.engines.procedure.SimEngineProcedure(project=None)

Bases: angr.engines.engine.SimEngine

An engine for running SimProcedures

process(state, procedure, ret_to=None, inline=None, force_addr=None, **kwargs)

Perform execution with a state.

Parameters:
  • state – The state with which to execute
  • procedure – An instance of a SimProcedure to run
  • ret_to – The address to return to when this procedure is finished
  • 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
Returns:

A SimSuccessors object categorizing the execution’s successor states

class angr.engines.hook.SimEngineHook(project=None)

Bases: angr.engines.engine.SimEngine

process(state, procedure=None, force_addr=None, **kwargs)

Perform execution with a state.

Parameters:
  • state – The state with which to execute
  • procedure – An instance of a SimProcedure to run, optional
  • ret_to – The address to return to when this procedure is finished
  • 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
Returns:

A SimSuccessors object categorizing the execution’s successor states

class angr.engines.syscall.SimEngineSyscall(project=None)

Bases: angr.engines.engine.SimEngine

process(state, **kwargs)
class angr.engines.unicorn.SimEngineUnicorn(project)

Bases: angr.engines.engine.SimEngine

Concrete execution in the Unicorn Engine, a fork of qemu.

process(state, step=None, extra_stop_points=None, inline=False, force_addr=None, **kwargs)
Parameters:
  • state – The state with which to execute
  • step – How many basic blocks we want to execute
  • extra_stop_points – A collection of addresses at which execution should halt
  • 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
Returns:

A SimSuccessors object categorizing the results of the run and whether it succeeded.

class angr.engines.failure.SimEngineFailure(project=None)

Bases: angr.engines.engine.SimEngine

process(state, *args, **kwargs)

Simulation Logging

class angr.state_plugins.sim_action.SimAction(state, region_type)

Bases: angr.state_plugins.sim_event.SimEvent

A SimAction represents a semantic action that an analyzed program performs.

Initializes the SimAction.

Parameters:state – the state that’s the SimAction is taking place in.
TMP = 'tmp'
REG = 'reg'
MEM = 'mem'
all_objects
tmp_deps
reg_deps
copy()
downsize()

Clears some low-level details (that take up memory) out of the SimAction.

class angr.state_plugins.sim_action.SimActionExit(state, target, condition=None, exit_type=None)

Bases: angr.state_plugins.sim_action.SimAction

An Exit action represents a (possibly conditional) jump.

CONDITIONAL = 'conditional'
DEFAULT = 'default'
all_objects
class angr.state_plugins.sim_action.SimActionConstraint(state, constraint, condition=None)

Bases: angr.state_plugins.sim_action.SimAction

A constraint action represents an extra constraint added during execution of a path.

all_objects
class angr.state_plugins.sim_action.SimActionOperation(state, op, exprs, result)

Bases: angr.state_plugins.sim_action.SimAction

An action representing an operation between variables and/or constants.

all_objects
class angr.state_plugins.sim_action.SimActionData(state, region_type, action, tmp=None, addr=None, size=None, data=None, condition=None, fallback=None, fd=None)

Bases: angr.state_plugins.sim_action.SimAction

A Data action represents a read or a write from memory, registers or a file.

READ = 'read'
WRITE = 'write'
OPERATE = 'operate'
downsize()
all_objects
tmp_deps
reg_deps
angr.state_plugins.sim_action_object.ast_stripping_op(f, *args, **kwargs)
angr.state_plugins.sim_action_object.ast_preserving_op(f, *args, **kwargs)
angr.state_plugins.sim_action_object.ast_stripping_decorator(f)
class angr.state_plugins.sim_action_object.SimActionObject(ast, reg_deps=None, tmp_deps=None)

Bases: object

A SimActionObject tracks an AST and its dependencies.

to_claripy()
copy()
SDiv(*args, **kwargs)
SMod(*args, **kwargs)
intersection(*args, **kwargs)
union(*args, **kwargs)
widen(*args, **kwargs)
angr.state_plugins.sim_action_object.make_methods()
class angr.state_plugins.sim_event.SimEvent(state, event_type, **kwargs)

Bases: object

Procedures

class angr.sim_procedure.SimProcedure(project=None, cc=None, symbolic_return=None, returns=None, is_syscall=False, is_stub=False, num_args=None, display_name=None, library_name=None, is_function=None, **kwargs)

Bases: object

A SimProcedure is a wonderful object which describes a procedure to run on a state.

You may subclass SimProcedure and override run(), replacing it with mutating self.state however you like, and then either returning a value or jumping away somehow.

A detailed discussion of programming SimProcedures may be found at https://docs.angr.io/docs/simprocedures.md

Parameters:arch – The architecture to use for this procedure

The following parameters are optional:

Parameters:
  • symbolic_return – Whether the procedure’s return value should be stubbed into a single symbolic variable constratined to the real return value
  • returns – Whether the procedure should return to its caller afterwards
  • is_syscall – Whether this procedure is a syscall
  • num_args – The number of arguments this procedure should extract
  • display_name – The name to use when displaying this procedure
  • cc – The SimCC to use for this procedure
  • sim_kwargs – Additional keyword arguments to be passed to run()
  • is_function – Whether this procedure emulates a function
execute(state, successors=None, arguments=None, ret_to=None)

Call this method with a SimState and a SimSuccessors to execute the procedure.

Alternately, successors may be none if this is an inline call. In that case, you should provide arguments to the function.

make_continuation(name)
NO_RET = False
ADDS_EXITS = False
IS_FUNCTION = True
ARGS_MISMATCH = False
local_vars = ()
run(*args, **kwargs)

Implement the actual procedure here!

static_exits(blocks)

Get new exits by performing static analysis and heuristics. This is a fast and best-effort approach to get new exits for scenarios where states are not available (e.g. when building a fast CFG).

Parameters:blocks (list) – Blocks that are executed before reaching this SimProcedure.
Returns:A list of tuples. Each tuple is (address, jumpkind).
Return type:list
should_add_successors
set_args(args)
arg(i)

Returns the ith argument. Raise a SimProcedureArgumentError if we don’t have such an argument available.

Parameters:i (int) – The index of the argument to get
Returns:The argument
Return type:object
inline_call(procedure, *arguments, **kwargs)

Call another SimProcedure in-line to retrieve its return value. Returns an instance of the procedure with the ret_expr property set.

Parameters:
  • procedure – The class of the procedure to execute
  • arguments – Any additional positional args will be used as arguments to the procedure call
  • sim_kwargs – Any additional keyword args will be passed as sim_kwargs to the procedure construtor
ret(expr=None)

Add an exit representing a return from this function. If this is not an inline call, grab a return address from the state and jump to it. If this is not an inline call, set a return expression with the calling convention.

call(addr, args, continue_at, cc=None)

Add an exit representing calling another function via pointer.

Parameters:
  • addr – The address of the function to call
  • args – The list of arguments to call the function with
  • continue_at – Later, when the called function returns, execution of the current procedure will continue in the named method.
  • cc – Optional: use this calling convention for calling the new function. Default is to use the current convention.
jump(addr)

Add an exit representing jumping to an address.

exit(exit_code)

Add an exit representing terminating the program.

ty_ptr(ty)
class angr.procedures.stubs.format_parser.FormatString(parser, components)

Bases: object

Describes a format string.

Takes a list of components which are either just strings or a FormatSpecifier.

SCANF_DELIMITERS = [b'\t', b'\n', b'\x0b', b'\r', b' ']
state
replace(startpos, args)

Implement printf - based on the stored format specifier information, format the values from the arg getter function args into a string.

Parameters:
  • startpos – The index of the first argument to be used by the first element of the format string
  • args – A function which, given an argument index, returns the integer argument to the current function at that index
Returns:

The result formatted string

interpret(startpos, args, addr=None, simfd=None)

implement scanf - extract formatted data from memory or a file according to the stored format specifiers and store them into the pointers extracted from args.

Parameters:
  • startpos – The index of the first argument corresponding to the first format element
  • args – A function which, given the index of an argument to the function, returns that argument
  • addr – The address in the memory to extract data from, or…
  • simfd – A file descriptor to use for reading data from
Returns:

The number of arguments parsed

class angr.procedures.stubs.format_parser.FormatSpecifier(string, length_spec, size, signed)

Bases: object

Describes a format specifier within a format string.

spec_type
class angr.procedures.stubs.format_parser.FormatParser(project=None, cc=None, symbolic_return=None, returns=None, is_syscall=False, is_stub=False, num_args=None, display_name=None, library_name=None, is_function=None, **kwargs)

Bases: angr.sim_procedure.SimProcedure

For SimProcedures relying on format strings.

ARGS_MISMATCH = True
basic_spec = {b'A': 'double', b'E': 'double', b'F': 'double', b'G': 'double', b'X': 'unsigned int', b'a': 'double', b'c': 'char', b'd': 'int', b'e': 'double', b'f': 'double', b'g': 'double', b'i': 'int', b'n': 'uintptr_t', b'o': 'unsigned int', b'p': 'uintptr_t', b's': 'char*', b'u': 'unsigned int', b'x': 'unsigned int'}
int_sign = {'signed': [b'd', b'i'], 'unsigned': [b'o', b'u', b'x', b'X']}
int_len_mod = {b'h': ('int16_t', 'uint16_t'), b'hh': ('char', 'uint8_t'), b'j': ('int64_t', 'uint64_t'), b'l': ('long', 'unsigned long'), b'll': ('int64_t', 'uint64_t'), b't': ('ptrdiff_t', 'ptrdiff_t'), b'z': ('ssize', 'size_t')}
other_types = {('string',): <function FormatParser.<lambda>>}
flags = ['#', '0', '\\-', ' ', '\\+', "\\'", 'I']
class angr.procedures.definitions.SimLibrary

Bases: object

A SimLibrary is the mechanism for describing a dynamic library’s API, its functions and metadata.

Any instance of this class (or its subclasses) found in the angr.procedures.definitions package will be automatically picked up and added to angr.SIM_LIBRARIES via all its names.

Variables:
  • fallback_cc – A mapping from architecture to the default calling convention that should be used if no other information is present. Contains some sane defaults for linux.
  • fallback_proc – A SimProcedure class that should be used to provide stub procedures. By default, ReturnUnconstrained.
copy()

Make a copy of this SimLibrary, allowing it to be mutated without affecting the global version.

Returns:A new SimLibrary object with the same library references but different dict/list references
update(other)

Augment this SimLibrary with the information from another SimLibrary

Parameters:other – The other SimLibrary
name

The first common name of this library, e.g. libc.so.6, or ‘??????’ if none are known.

set_library_names(*names)

Set some common names of this library by which it may be referred during linking

Parameters:names – Any number of string library names may be passed as varargs.
set_default_cc(arch_name, cc_cls)

Set the default calling convention used for this library under a given architecture

Parameters:arch_name – The string name of the architecture, i.e. the .name field from archinfo.
Parm cc_cls:The SimCC class (not an instance!) to use
set_non_returning(*names)

Mark some functions in this class as never returning, i.e. loops forever or terminates execution

Parameters:names – Any number of string function names may be passed as varargs
set_prototype(name, proto)

Set the prototype of a function in the form of a SimTypeFunction containing argument and return types

Parameters:
  • name – The name of the function as a string
  • proto – The prototype of the function as a SimTypeFunction
set_prototypes(protos)

Set the prototypes of many functions

Parameters:protos – Dictionary mapping function names to SimTypeFunction objects
set_c_prototype(c_decl)

Set the prototype of a function in the form of a C-style function declaration.

Parameters:c_decl (str) – The C-style declaration of the function.
Returns:A tuple of (function name, function prototype)
Return type:tuple
add(name, proc_cls, **kwargs)

Add a function implementation fo the library.

Parameters:
  • name – The name of the function as a string
  • proc_cls – The implementation of the function as a SimProcedure _class_, not instance
  • kwargs – Any additional parameters to the procedure class constructor may be passed as kwargs
add_all_from_dict(dictionary, **kwargs)

Batch-add function implementations to the library.

Parameters:
  • dictionary – A mapping from name to procedure class, i.e. the first two arguments to add()
  • kwargs – Any additional kwargs will be passed to the constructors of _each_ procedure class
add_alias(name, *alt_names)

Add some duplicate names for a given function. The original function’s implementation must already be registered.

Parameters:
  • name – The name of the function for which an implementation is already present
  • alt_names – Any number of alternate names may be passed as varargs
get(name, arch)

Get an implementation of the given function specialized for the given arch, or a stub procedure if none exists.

Parameters:
  • name – The name of the function as a string
  • arch – The architecure to use, as either a string or an archinfo.Arch instance
Returns:

A SimProcedure instance representing the function as found in the library

get_stub(name, arch)

Get a stub procedure for the given function, regardless of if a real implementation is available. This will apply any metadata, such as a default calling convention or a function prototype.

By stub, we pretty much always mean a ReturnUnconstrained SimProcedure with the appropriate display name and metadata set. This will appear in state.history.descriptions as <SimProcedure display_name (stub)>

Parameters:
  • name – The name of the function as a string
  • arch – The architecture to use, as either a string or an archinfo.Arch instance
Returns:

A SimProcedure instance representing a plausable stub as could be found in the library.

has_metadata(name)

Check if a function has either an implementation or any metadata associated with it

Parameters:name – The name of the function as a string
Returns:A bool indicating if anything is known about the function
has_implementation(name)

Check if a function has an implementation associated with it

Parameters:name – The name of the function as a string
Returns:A bool indicating if an implementation of the function is available
has_prototype(func_name)

Check if a function has a prototype associated with it.

Parameters:func_name (str) – The name of the function.
Returns:A bool indicating if a prototype of the function is available.
Return type:bool
class angr.procedures.definitions.SimSyscallLibrary

Bases: angr.procedures.definitions.SimLibrary

SimSyscallLibrary is a specialized version of SimLibrary for dealing not with a dynamic library’s API but rather an operating system’s syscall API. Because this interface is inherantly lower-level than a dynamic library, many parts of this class has been changed to store data based on an “ABI name” (ABI = application binary interface, like an API but for when there’s no programming language) instead of an architecture. An ABI name is just an arbitrary string with which a calling convention and a syscall numbering is associated.

All the SimLibrary methods for adding functions still work, but now there’s an additional layer on top that associates them with numbers.

copy()
update(other)
minimum_syscall_number(abi)
Parameters:abi – The abi to evaluate
Returns:The smallest syscall number known for the given abi
maximum_syscall_number(abi)
Parameters:abi – The abi to evaluate
Returns:The largest syscall number known for the given abi
add_number_mapping(abi, number, name)

Associate a syscall number with the name of a function present in the underlying SimLibrary

Parameters:
  • abi – The abi for which this mapping applies
  • number – The syscall number
  • name – The name of the function
add_number_mapping_from_dict(abi, mapping)

Batch-associate syscall numbers with names of functions present in the underlying SimLibrary

Parameters:
  • abi – The abi for which this mapping applies
  • mapping – A dict mapping syscall numbers to function names
set_abi_cc(abi, cc_cls)

Set the default calling convention for an abi

Parameters:
  • abi – The name of the abi
  • cc_cls – A SimCC _class_, not an instance, that should be used for syscalls using the abi
get(number, arch, abi_list=())

The get() function for SimSyscallLibrary looks a little different from its original version.

Instead of providing a name, you provide a number, and you additionally provide a list of abi names that are applicable. The first abi for which the number is present in the mapping will be chosen. This allows for the easy abstractions of architectures like ARM or MIPS linux for which there are many ABIs that can be used at any time by using syscall numbers from various ranges. If no abi knows about the number, the stub procedure with the name “sys_%d” will be used.

Parameters:
  • number – The syscall number
  • arch – The architecture being worked with, as either a string name or an archinfo.Arch
  • abi_list – A list of ABI names that could be used
Returns:

A SimProcedure representing the implementation of the given syscall, or a stub if no implementation is available

get_stub(number, arch, abi_list=())

Pretty much the intersection of SimLibrary.get_stub() and SimSyscallLibrary.get().

Parameters:
  • number – The syscall number
  • arch – The architecture being worked with, as either a string name or an archinfo.Arch
  • abi_list – A list of ABI names that could be used
Returns:

A SimProcedure representing a plausable stub that could model the syscall

has_metadata(number, arch, abi_list=())

Pretty much the intersection of SimLibrary.has_metadata() and SimSyscallLibrary.get().

Parameters:
  • number – The syscall number
  • arch – The architecture being worked with, as either a string name or an archinfo.Arch
  • abi_list – A list of ABI names that could be used
Returns:

A bool of whether or not any implementation or metadata is known about the given syscall

has_implementation(number, arch, abi_list=())

Pretty much the intersection of SimLibrary.has_implementation() and SimSyscallLibrary.get().

Parameters:
  • number – The syscall number
  • arch – The architecture being worked with, as either a string name or an archinfo.Arch
  • abi_list – A list of ABI names that could be used
Returns:

A bool of whether or not an implementation of the syscall is available

Calling Conventions and Types

class angr.calling_conventions.PointerWrapper(value)

Bases: object

class angr.calling_conventions.AllocHelper(ptr, grow_like_stack, reverse_result)

Bases: object

dump(val, state, endness='Iend_BE')
class angr.calling_conventions.SimFunctionArgument(size)

Bases: object

check_value(value)
set_value(state, value, **kwargs)
get_value(state, **kwargs)
class angr.calling_conventions.SimRegArg(reg_name, size, alt_offsets=None)

Bases: angr.calling_conventions.SimFunctionArgument

set_value(state, value, endness=None, size=None, **kwargs)
get_value(state, endness=None, size=None, **kwargs)
class angr.calling_conventions.SimStackArg(stack_offset, size)

Bases: angr.calling_conventions.SimFunctionArgument

set_value(state, value, endness=None, stack_base=None)
get_value(state, endness=None, stack_base=None, size=None)
class angr.calling_conventions.SimComboArg(locations)

Bases: angr.calling_conventions.SimFunctionArgument

set_value(state, value, endness=None, **kwargs)
get_value(state, endness=None, **kwargs)
class angr.calling_conventions.ArgSession(cc)

Bases: object

A class to keep track of the state accumulated in laying parameters out into memory

next_arg(is_fp, size=None)
upsize_arg(arg, is_fp, size)
class angr.calling_conventions.SimCC(arch, args=None, ret_val=None, sp_delta=None, func_ty=None)

Bases: object

A calling convention allows you to extract from a state the data passed from function to function by calls and returns. Most of the methods provided by SimCC that operate on a state assume that the program is just after a call but just before stack frame allocation, though this may be overridden with the stack_base parameter to each individual method.

This is the base class for all calling conventions.

An instance of this class allows it to be tweaked to the way a specific function should be called.

Parameters:
  • arch – The Archinfo arch for this CC
  • args – A list of SimFunctionArguments describing where the arguments go
  • ret_val – A SimFunctionArgument describing where the return value goes
  • sp_delta – The amount the stack pointer changes over the course of this function - CURRENTLY UNUSED
  • func_ty – A SimTypeFunction for the function itself, or a string that can be parsed into a SimTypeFunction instance.

Example func_ty strings: >>> “int func(char*, int)” >>> “int f(int, int, int*);” Function names are ignored.

classmethod from_arg_kinds(arch, fp_args, ret_fp=False, sizes=None, sp_delta=None, func_ty=None)

Get an instance of the class that will extract floating-point/integral args correctly.

Parameters:
  • arch – The Archinfo arch for this CC
  • fp_args – A list, with one entry for each argument the function can take. True if the argument is fp, false if it is integral.
  • ret_fp – True if the return value for the function is fp.
  • sizes – Optional: A list, with one entry for each argument the function can take. Each entry is the size of the corresponding argument in bytes.
  • sp_delta – The amount the stack pointer changes over the course of this function - CURRENTLY UNUSED
Parmm func_ty:

A SimType for the function itself

ARG_REGS = None
FP_ARG_REGS = None
STACKARG_SP_BUFF = 0
STACKARG_SP_DIFF = 0
CALLER_SAVED_REGS = None
RETURN_ADDR = None
RETURN_VAL = None
FP_RETURN_VAL = None
ARCH = None
CALLEE_CLEANUP = False
STACK_ALIGNMENT = 1
int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values Does not take into account customizations.

Returns an iterator of SimFunctionArguments

both_args

Iterate through all the possible arg positions that can be used to store any kind of argument Does not take into account customizations.

Returns an iterator of SimFunctionArguments

fp_args

Iterate through all the possible arg positions that can only be used to store floating point values Does not take into account customizations.

Returns an iterator of SimFunctionArguments

is_fp_arg(arg)

This should take a SimFunctionArgument instance and return whether or not that argument is a floating-point argument.

Returns True for MUST be a floating point arg,
False for MUST NOT be a floating point arg, None for when it can be either.
class ArgSession(cc)

Bases: object

A class to keep track of the state accumulated in laying parameters out into memory

next_arg(is_fp, size=None)
upsize_arg(arg, is_fp, size)
arg_session

Return an arg session.

A session provides the control interface necessary to describe how integral and floating-point arguments are laid out into memory. The default behavior is that there are a finite list of int-only and fp-only argument slots, and an infinite number of generic slots, and when an argument of a given type is requested, the most slot available is used. If you need different behavior, subclass ArgSession.

stack_space(args)
Parameters:args – A list of SimFunctionArguments
Returns:The number of bytes that should be allocated on the stack to store all these args, NOT INCLUDING the return address.
return_val

The location the return value is stored.

fp_return_val
return_addr

The location the return address is stored.

static is_fp_value(val)
arg_locs(is_fp=None, sizes=None)

Pass this a list of whether each parameter is floating-point or not, and get back a list of SimFunctionArguments. Optionally, pass a list of argument sizes (in bytes) as well.

If you’ve customized this CC, this will sanity-check the provided locations with the given list.

arg(state, index, stack_base=None)

Returns a bitvector expression representing the nth argument of a function.

stack_base is an optional pointer to the top of the stack at the function start. If it is not specified, use the current stack pointer.

WARNING: this assumes that none of the arguments are floating-point and they’re all single-word-sized, unless you’ve customized this CC.

get_args(state, is_fp=None, sizes=None, stack_base=None)

is_fp should be a list of booleans specifying whether each corresponding argument is floating-point - True for fp and False for int. For a shorthand to assume that all the parameters are int, pass the number of parameters as an int.

If you’ve customized this CC, you may omit this parameter entirely. If it is provided, it is used for sanity-checking.

sizes is an optional list of argument sizes, in bytes. Be careful about using this if you’ve made explicit the arg locations, since it might decide to combine two locations into one if an arg is too big.

stack_base is an optional pointer to the top of the stack at the function start. If it is not specified, use the current stack pointer.

Returns a list of bitvector expressions representing the arguments of a function.

setup_callsite(state, ret_addr, args, stack_base=None, alloc_base=None, grow_like_stack=True)

This function performs the actions of the caller getting ready to jump into a function.

Parameters:
  • state – The SimState to operate on
  • ret_addr – The address to return to when the called function finishes
  • args – The list of arguments that that the called function will see
  • 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

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 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 sequencial allocations happen at increasing addresses.

teardown_callsite(state, return_val=None, arg_types=None, force_callee_cleanup=False)

This function performs the actions of the callee as it’s getting ready to return. It returns the address to return to.

Parameters:
  • state – The state to mutate
  • return_val – The value to return
  • arg_types – The fp-ness of each of the args. Used to calculate sizes to clean up
  • force_callee_cleanup – If we should clean up the stack allocation for the arguments even if it’s not the callee’s job to do so

TODO: support the stack_base parameter from setup_callsite…? Does that make sense in this context? Maybe it could make sense by saying that you pass it in as something like the “saved base pointer” value?

get_return_val(state, is_fp=None, size=None, stack_base=None)

Get the return value out of the given state

set_return_val(state, val, is_fp=None, size=None, stack_base=None)

Set the return value into the given state

static find_cc(arch, args, sp_delta)

Pinpoint the best-fit calling convention and return the corresponding SimCC instance, or None if no fit is found.

Parameters:
  • arch (Arch) – An ArchX instance. Can be obtained from archinfo.
  • args (list) – A list of arguments.
  • sp_delta (int) – The change of stack pointer before and after the call is made.
Returns:

A calling convention instance, or None if none of the SimCC subclasses seems to fit the arguments provided.

Return type:

SimCC or None

class angr.calling_conventions.SimLyingRegArg(name)

Bases: angr.calling_conventions.SimRegArg

A register that LIES about the types it holds

get_value(state, size=None, endness=None, **kwargs)
set_value(state, val, size=None, endness=None, **kwargs)
class angr.calling_conventions.SimCCCdecl(arch, args=None, ret_val=None, sp_delta=None, func_ty=None)

Bases: angr.calling_conventions.SimCC

Parameters:
  • arch – The Archinfo arch for this CC
  • args – A list of SimFunctionArguments describing where the arguments go
  • ret_val – A SimFunctionArgument describing where the return value goes
  • sp_delta – The amount the stack pointer changes over the course of this function - CURRENTLY UNUSED
  • func_ty – A SimTypeFunction for the function itself, or a string that can be parsed into a SimTypeFunction instance.

Example func_ty strings: >>> “int func(char*, int)” >>> “int f(int, int, int*);” Function names are ignored.

ARG_REGS = []
FP_ARG_REGS = []
STACKARG_SP_DIFF = 4
RETURN_VAL = <eax>
FP_RETURN_VAL = <st0>
RETURN_ADDR = [0x0]
ARCH

alias of archinfo.arch_x86.ArchX86

class angr.calling_conventions.SimCCStdcall(arch, args=None, ret_val=None, sp_delta=None, func_ty=None)

Bases: angr.calling_conventions.SimCCCdecl

Parameters:
  • arch – The Archinfo arch for this CC
  • args – A list of SimFunctionArguments describing where the arguments go
  • ret_val – A SimFunctionArgument describing where the return value goes
  • sp_delta – The amount the stack pointer changes over the course of this function - CURRENTLY UNUSED
  • func_ty – A SimTypeFunction for the function itself, or a string that can be parsed into a SimTypeFunction instance.

Example func_ty strings: >>> “int func(char*, int)” >>> “int f(int, int, int*);” Function names are ignored.

CALLEE_CLEANUP = True
class angr.calling_conventions.SimCCMicrosoftAMD64(arch, args=None, ret_val=None, sp_delta=None, func_ty=None)

Bases: angr.calling_conventions.SimCC

Parameters:
  • arch – The Archinfo arch for this CC
  • args – A list of SimFunctionArguments describing where the arguments go
  • ret_val – A SimFunctionArgument describing where the return value goes
  • sp_delta – The amount the stack pointer changes over the course of this function - CURRENTLY UNUSED
  • func_ty – A SimTypeFunction for the function itself, or a string that can be parsed into a SimTypeFunction instance.

Example func_ty strings: >>> “int func(char*, int)” >>> “int f(int, int, int*);” Function names are ignored.

ARG_REGS = ['rcx', 'rdx', 'r8', 'r9']
FP_ARG_REGS = ['xmm0', 'xmm1', 'xmm2', 'xmm3']
STACKARG_SP_DIFF = 8
STACKARG_SP_BUFF = 32
RETURN_VAL = <rax>
FP_RETURN_VAL = <xmm0>
RETURN_ADDR = [0x0]
ARCH

alias of archinfo.arch_amd64.ArchAMD64

class angr.calling_conventions.SimCCX86LinuxSyscall(arch, args=None, ret_val=None, sp_delta=None, func_ty=None)

Bases: angr.calling_conventions.SimCC

Parameters:
  • arch – The Archinfo arch for this CC
  • args – A list of SimFunctionArguments describing where the arguments go
  • ret_val – A SimFunctionArgument describing where the return value goes
  • sp_delta – The amount the stack pointer changes over the course of this function - CURRENTLY UNUSED
  • func_ty – A SimTypeFunction for the function itself, or a string that can be parsed into a SimTypeFunction instance.

Example func_ty strings: >>> “int func(char*, int)” >>> “int f(int, int, int*);” Function names are ignored.

ARG_REGS = ['ebx', 'ecx', 'edx', 'esi', 'edi', 'ebp']
FP_ARG_REGS = []
RETURN_VAL = <eax>
RETURN_ADDR = <ip_at_syscall>
ARCH

alias of archinfo.arch_x86.ArchX86

static syscall_num(state)
class angr.calling_conventions.SimCCX86WindowsSyscall(arch, args=None, ret_val=None, sp_delta=None, func_ty=None)

Bases: angr.calling_conventions.SimCC

Parameters:
  • arch – The Archinfo arch for this CC
  • args – A list of SimFunctionArguments describing where the arguments go
  • ret_val – A SimFunctionArgument describing where the return value goes
  • sp_delta – The amount the stack pointer changes over the course of this function - CURRENTLY UNUSED
  • func_ty – A SimTypeFunction for the function itself, or a string that can be parsed into a SimTypeFunction instance.

Example func_ty strings: >>> “int func(char*, int)” >>> “int f(int, int, int*);” Function names are ignored.

ARG_REGS = []
FP_ARG_REGS = []
RETURN_VAL = <eax>
RETURN_ADDR = <ip_at_syscall>
ARCH

alias of archinfo.arch_x86.ArchX86

static syscall_num(state)
class angr.calling_conventions.SimCCSystemVAMD64(arch, args=None, ret_val=None, sp_delta=None, func_ty=None)

Bases: angr.calling_conventions.SimCC

ARG_REGS = ['rdi', 'rsi', 'rdx', 'rcx', 'r8', 'r9']
FP_ARG_REGS = ['xmm0', 'xmm1', 'xmm2', 'xmm3', 'xmm4', 'xmm5', 'xmm6', 'xmm7']
STACKARG_SP_DIFF = 8
CALLER_SAVED_REGS = ['rdi', 'rsi', 'rdx', 'rcx', 'r8', 'r9', 'r10', 'r11', 'rax']
RETURN_ADDR = [0x0]
RETURN_VAL = <rax>
FP_RETURN_VAL = <xmm0>
ARCH

alias of archinfo.arch_amd64.ArchAMD64

STACK_ALIGNMENT = 16
class angr.calling_conventions.SimCCAMD64LinuxSyscall(arch, args=None, ret_val=None, sp_delta=None, func_ty=None)

Bases: angr.calling_conventions.SimCC

Parameters:
  • arch – The Archinfo arch for this CC
  • args – A list of SimFunctionArguments describing where the arguments go
  • ret_val – A SimFunctionArgument describing where the return value goes
  • sp_delta – The amount the stack pointer changes over the course of this function - CURRENTLY UNUSED
  • func_ty – A SimTypeFunction for the function itself, or a string that can be parsed into a SimTypeFunction instance.

Example func_ty strings: >>> “int func(char*, int)” >>> “int f(int, int, int*);” Function names are ignored.

ARG_REGS = ['rdi', 'rsi', 'rdx', 'r10', 'r8', 'r9']
RETURN_VAL = <rax>
RETURN_ADDR = <ip_at_syscall>
ARCH

alias of archinfo.arch_amd64.ArchAMD64

static syscall_num(state)
class angr.calling_conventions.SimCCAMD64WindowsSyscall(arch, args=None, ret_val=None, sp_delta=None, func_ty=None)

Bases: angr.calling_conventions.SimCC

Parameters:
  • arch – The Archinfo arch for this CC
  • args – A list of SimFunctionArguments describing where the arguments go
  • ret_val – A SimFunctionArgument describing where the return value goes
  • sp_delta – The amount the stack pointer changes over the course of this function - CURRENTLY UNUSED
  • func_ty – A SimTypeFunction for the function itself, or a string that can be parsed into a SimTypeFunction instance.

Example func_ty strings: >>> “int func(char*, int)” >>> “int f(int, int, int*);” Function names are ignored.

ARG_REGS = []
FP_ARG_REGS = []
RETURN_VAL = <rax>
RETURN_ADDR = <ip_at_syscall>
ARCH

alias of archinfo.arch_amd64.ArchAMD64

static syscall_num(state)
class angr.calling_conventions.SimCCARM(arch, args=None, ret_val=None, sp_delta=None, func_ty=None)

Bases: angr.calling_conventions.SimCC

Parameters:
  • arch – The Archinfo arch for this CC
  • args – A list of SimFunctionArguments describing where the arguments go
  • ret_val – A SimFunctionArgument describing where the return value goes
  • sp_delta – The amount the stack pointer changes over the course of this function - CURRENTLY UNUSED
  • func_ty – A SimTypeFunction for the function itself, or a string that can be parsed into a SimTypeFunction instance.

Example func_ty strings: >>> “int func(char*, int)” >>> “int f(int, int, int*);” Function names are ignored.

ARG_REGS = ['r0', 'r1', 'r2', 'r3']
FP_ARG_REGS = []
RETURN_ADDR = <lr>
RETURN_VAL = <r0>
ARCH

alias of archinfo.arch_arm.ArchARM

class angr.calling_conventions.SimCCARMLinuxSyscall(arch, args=None, ret_val=None, sp_delta=None, func_ty=None)

Bases: angr.calling_conventions.SimCC

Parameters:
  • arch – The Archinfo arch for this CC
  • args – A list of SimFunctionArguments describing where the arguments go
  • ret_val – A SimFunctionArgument describing where the return value goes
  • sp_delta – The amount the stack pointer changes over the course of this function - CURRENTLY UNUSED
  • func_ty – A SimTypeFunction for the function itself, or a string that can be parsed into a SimTypeFunction instance.

Example func_ty strings: >>> “int func(char*, int)” >>> “int f(int, int, int*);” Function names are ignored.

ARG_REGS = ['r0', 'r1', 'r2', 'r3']
FP_ARG_REGS = []
RETURN_ADDR = <ip_at_syscall>
RETURN_VAL = <r0>
ARCH

alias of archinfo.arch_arm.ArchARM

static syscall_num(state)
class angr.calling_conventions.SimCCAArch64(arch, args=None, ret_val=None, sp_delta=None, func_ty=None)

Bases: angr.calling_conventions.SimCC

Parameters:
  • arch – The Archinfo arch for this CC
  • args – A list of SimFunctionArguments describing where the arguments go
  • ret_val – A SimFunctionArgument describing where the return value goes
  • sp_delta – The amount the stack pointer changes over the course of this function - CURRENTLY UNUSED
  • func_ty – A SimTypeFunction for the function itself, or a string that can be parsed into a SimTypeFunction instance.

Example func_ty strings: >>> “int func(char*, int)” >>> “int f(int, int, int*);” Function names are ignored.

ARG_REGS = ['x0', 'x1', 'x2', 'x3', 'x4', 'x5', 'x6', 'x7']
FP_ARG_REGS = []
RETURN_ADDR = <lr>
RETURN_VAL = <x0>
ARCH

alias of archinfo.arch_aarch64.ArchAArch64

class angr.calling_conventions.SimCCAArch64LinuxSyscall(arch, args=None, ret_val=None, sp_delta=None, func_ty=None)

Bases: angr.calling_conventions.SimCC

Parameters:
  • arch – The Archinfo arch for this CC
  • args – A list of SimFunctionArguments describing where the arguments go
  • ret_val – A SimFunctionArgument describing where the return value goes
  • sp_delta – The amount the stack pointer changes over the course of this function - CURRENTLY UNUSED
  • func_ty – A SimTypeFunction for the function itself, or a string that can be parsed into a SimTypeFunction instance.

Example func_ty strings: >>> “int func(char*, int)” >>> “int f(int, int, int*);” Function names are ignored.

ARG_REGS = ['x0', 'x1', 'x2', 'x3', 'x4', 'x5', 'x6', 'x7']
FP_ARG_REGS = []
RETURN_VAL = <x0>
RETURN_ADDR = <ip_at_syscall>
ARCH

alias of archinfo.arch_aarch64.ArchAArch64

static syscall_num(state)
class angr.calling_conventions.SimCCO32(arch, args=None, ret_val=None, sp_delta=None, func_ty=None)

Bases: angr.calling_conventions.SimCC

Parameters:
  • arch – The Archinfo arch for this CC
  • args – A list of SimFunctionArguments describing where the arguments go
  • ret_val – A SimFunctionArgument describing where the return value goes
  • sp_delta – The amount the stack pointer changes over the course of this function - CURRENTLY UNUSED
  • func_ty – A SimTypeFunction for the function itself, or a string that can be parsed into a SimTypeFunction instance.

Example func_ty strings: >>> “int func(char*, int)” >>> “int f(int, int, int*);” Function names are ignored.

ARG_REGS = ['a0', 'a1', 'a2', 'a3']
FP_ARG_REGS = []
STACKARG_SP_BUFF = 16
RETURN_ADDR = <lr>
RETURN_VAL = <v0>
ARCH

alias of archinfo.arch_mips32.ArchMIPS32

class angr.calling_conventions.SimCCO32LinuxSyscall(arch, args=None, ret_val=None, sp_delta=None, func_ty=None)

Bases: angr.calling_conventions.SimCC

Parameters:
  • arch – The Archinfo arch for this CC
  • args – A list of SimFunctionArguments describing where the arguments go
  • ret_val – A SimFunctionArgument describing where the return value goes
  • sp_delta – The amount the stack pointer changes over the course of this function - CURRENTLY UNUSED
  • func_ty – A SimTypeFunction for the function itself, or a string that can be parsed into a SimTypeFunction instance.

Example func_ty strings: >>> “int func(char*, int)” >>> “int f(int, int, int*);” Function names are ignored.

ARG_REGS = ['a0', 'a1', 'a2', 'a3']
FP_ARG_REGS = []
RETURN_VAL = <v0>
RETURN_ADDR = <ip_at_syscall>
ARCH

alias of archinfo.arch_mips32.ArchMIPS32

static syscall_num(state)
class angr.calling_conventions.SimCCO64(arch, args=None, ret_val=None, sp_delta=None, func_ty=None)

Bases: angr.calling_conventions.SimCC

Parameters:
  • arch – The Archinfo arch for this CC
  • args – A list of SimFunctionArguments describing where the arguments go
  • ret_val – A SimFunctionArgument describing where the return value goes
  • sp_delta – The amount the stack pointer changes over the course of this function - CURRENTLY UNUSED
  • func_ty – A SimTypeFunction for the function itself, or a string that can be parsed into a SimTypeFunction instance.

Example func_ty strings: >>> “int func(char*, int)” >>> “int f(int, int, int*);” Function names are ignored.

ARG_REGS = ['a0', 'a1', 'a2', 'a3']
FP_ARG_REGS = []
STACKARG_SP_BUFF = 32
RETURN_ADDR = <lr>
RETURN_VAL = <v0>
ARCH

alias of archinfo.arch_mips64.ArchMIPS64

class angr.calling_conventions.SimCCO64LinuxSyscall(arch, args=None, ret_val=None, sp_delta=None, func_ty=None)

Bases: angr.calling_conventions.SimCC

Parameters:
  • arch – The Archinfo arch for this CC
  • args – A list of SimFunctionArguments describing where the arguments go
  • ret_val – A SimFunctionArgument describing where the return value goes
  • sp_delta – The amount the stack pointer changes over the course of this function - CURRENTLY UNUSED
  • func_ty – A SimTypeFunction for the function itself, or a string that can be parsed into a SimTypeFunction instance.

Example func_ty strings: >>> “int func(char*, int)” >>> “int f(int, int, int*);” Function names are ignored.

ARG_REGS = ['a0', 'a1', 'a2', 'a3']
FP_ARG_REGS = []
RETURN_VAL = <v0>
RETURN_ADDR = <ip_at_syscall>
ARCH

alias of archinfo.arch_mips64.ArchMIPS64

static syscall_num(state)
class angr.calling_conventions.SimCCPowerPC(arch, args=None, ret_val=None, sp_delta=None, func_ty=None)

Bases: angr.calling_conventions.SimCC

Parameters:
  • arch – The Archinfo arch for this CC
  • args – A list of SimFunctionArguments describing where the arguments go
  • ret_val – A SimFunctionArgument describing where the return value goes
  • sp_delta – The amount the stack pointer changes over the course of this function - CURRENTLY UNUSED
  • func_ty – A SimTypeFunction for the function itself, or a string that can be parsed into a SimTypeFunction instance.

Example func_ty strings: >>> “int func(char*, int)” >>> “int f(int, int, int*);” Function names are ignored.

ARG_REGS = ['r3', 'r4', 'r5', 'r6', 'r7', 'r8', 'r9', 'r10']
FP_ARG_REGS = []
STACKARG_SP_BUFF = 8
RETURN_ADDR = <lr>
RETURN_VAL = <r3>
ARCH

alias of archinfo.arch_ppc32.ArchPPC32

class angr.calling_conventions.SimCCPowerPCLinuxSyscall(arch, args=None, ret_val=None, sp_delta=None, func_ty=None)

Bases: angr.calling_conventions.SimCC

Parameters:
  • arch – The Archinfo arch for this CC
  • args – A list of SimFunctionArguments describing where the arguments go
  • ret_val – A SimFunctionArgument describing where the return value goes
  • sp_delta – The amount the stack pointer changes over the course of this function - CURRENTLY UNUSED
  • func_ty – A SimTypeFunction for the function itself, or a string that can be parsed into a SimTypeFunction instance.

Example func_ty strings: >>> “int func(char*, int)” >>> “int f(int, int, int*);” Function names are ignored.

ARG_REGS = ['r3', 'r4', 'r5', 'r6', 'r7', 'r8', 'r9', 'r10']
FP_ARG_REGS = []
RETURN_VAL = <r3>
RETURN_ADDR = <ip_at_syscall>
ARCH

alias of archinfo.arch_ppc32.ArchPPC32

static syscall_num(state)
class angr.calling_conventions.SimCCPowerPC64(arch, args=None, ret_val=None, sp_delta=None, func_ty=None)

Bases: angr.calling_conventions.SimCC

Parameters:
  • arch – The Archinfo arch for this CC
  • args – A list of SimFunctionArguments describing where the arguments go
  • ret_val – A SimFunctionArgument describing where the return value goes
  • sp_delta – The amount the stack pointer changes over the course of this function - CURRENTLY UNUSED
  • func_ty – A SimTypeFunction for the function itself, or a string that can be parsed into a SimTypeFunction instance.

Example func_ty strings: >>> “int func(char*, int)” >>> “int f(int, int, int*);” Function names are ignored.

ARG_REGS = ['r3', 'r4', 'r5', 'r6', 'r7', 'r8', 'r9', 'r10']
FP_ARG_REGS = []
STACKARG_SP_BUFF = 112
RETURN_ADDR = <lr>
RETURN_VAL = <r3>
ARCH

alias of archinfo.arch_ppc64.ArchPPC64

class angr.calling_conventions.SimCCPowerPC64LinuxSyscall(arch, args=None, ret_val=None, sp_delta=None, func_ty=None)

Bases: angr.calling_conventions.SimCC

Parameters:
  • arch – The Archinfo arch for this CC
  • args – A list of SimFunctionArguments describing where the arguments go
  • ret_val – A SimFunctionArgument describing where the return value goes
  • sp_delta – The amount the stack pointer changes over the course of this function - CURRENTLY UNUSED
  • func_ty – A SimTypeFunction for the function itself, or a string that can be parsed into a SimTypeFunction instance.

Example func_ty strings: >>> “int func(char*, int)” >>> “int f(int, int, int*);” Function names are ignored.

ARG_REGS = []
FP_ARG_REGS = []
RETURN_VAL = <r3>
RETURN_ADDR = <ip_at_syscall>
ARCH

alias of archinfo.arch_ppc64.ArchPPC64

static syscall_num(state)
class angr.calling_conventions.SimCCUnknown(arch, args=None, ret_val=None, sp_delta=None, func_ty=None)

Bases: angr.calling_conventions.SimCC

Represent an unknown calling convention.

Parameters:
  • arch – The Archinfo arch for this CC
  • args – A list of SimFunctionArguments describing where the arguments go
  • ret_val – A SimFunctionArgument describing where the return value goes
  • sp_delta – The amount the stack pointer changes over the course of this function - CURRENTLY UNUSED
  • func_ty – A SimTypeFunction for the function itself, or a string that can be parsed into a SimTypeFunction instance.

Example func_ty strings: >>> “int func(char*, int)” >>> “int f(int, int, int*);” Function names are ignored.

class angr.calling_conventions.SimCCS390X(arch, args=None, ret_val=None, sp_delta=None, func_ty=None)

Bases: angr.calling_conventions.SimCC

Parameters:
  • arch – The Archinfo arch for this CC
  • args – A list of SimFunctionArguments describing where the arguments go
  • ret_val – A SimFunctionArgument describing where the return value goes
  • sp_delta – The amount the stack pointer changes over the course of this function - CURRENTLY UNUSED
  • func_ty – A SimTypeFunction for the function itself, or a string that can be parsed into a SimTypeFunction instance.

Example func_ty strings: >>> “int func(char*, int)” >>> “int f(int, int, int*);” Function names are ignored.

ARG_REGS = ['r2', 'r3', 'r4', 'r5', 'r6']
FP_ARG_REGS = ['f0', 'f2', 'f4', 'f6']
STACKARG_SP_BUFF = 160
RETURN_ADDR = <r14>
RETURN_VAL = <r2>
ARCH

alias of archinfo.arch_s390x.ArchS390X

class angr.calling_conventions.SimCCS390XLinuxSyscall(arch, args=None, ret_val=None, sp_delta=None, func_ty=None)

Bases: angr.calling_conventions.SimCC

Parameters:
  • arch – The Archinfo arch for this CC
  • args – A list of SimFunctionArguments describing where the arguments go
  • ret_val – A SimFunctionArgument describing where the return value goes
  • sp_delta – The amount the stack pointer changes over the course of this function - CURRENTLY UNUSED
  • func_ty – A SimTypeFunction for the function itself, or a string that can be parsed into a SimTypeFunction instance.

Example func_ty strings: >>> “int func(char*, int)” >>> “int f(int, int, int*);” Function names are ignored.

ARG_REGS = ['r2', 'r3', 'r4', 'r5', 'r6', 'r7']
FP_ARG_REGS = []
RETURN_VAL = <r2>
RETURN_ADDR = <ip_at_syscall>
ARCH

alias of archinfo.arch_s390x.ArchS390X

static syscall_num(state)
angr.calling_conventions.register_default_cc(arch, cc)
angr.calling_conventions.register_syscall_cc(arch, os, cc)
class angr.sim_variable.SimVariable(ident=None, name=None, region=None, category=None)

Bases: object

Parameters:
  • ident – A unique identifier provided by user or the program. Usually a string.
  • name (str) – Name of this variable.
ident
name
region
category
phi
class angr.sim_variable.SimConstantVariable(ident=None, value=None, region=None)

Bases: angr.sim_variable.SimVariable

value
class angr.sim_variable.SimTemporaryVariable(tmp_id)

Bases: angr.sim_variable.SimVariable

tmp_id
class angr.sim_variable.SimRegisterVariable(reg_offset, size, ident=None, name=None, region=None, category=None)

Bases: angr.sim_variable.SimVariable

reg
size
class angr.sim_variable.SimRegisterVariablePhi(ident=None, name=None, region=None, variables=None)

Bases: angr.sim_variable.SimRegisterVariable

variables
phi
class angr.sim_variable.SimMemoryVariable(addr, size, ident=None, name=None, region=None, category=None)

Bases: angr.sim_variable.SimVariable

addr
size
class angr.sim_variable.SimMemoryVariablePhi(ident=None, name=None, region=None, variables=None)

Bases: angr.sim_variable.SimMemoryVariable

variables
phi
class angr.sim_variable.SimStackVariable(offset, size, base='sp', base_addr=None, ident=None, name=None, region=None, category=None)

Bases: angr.sim_variable.SimMemoryVariable

base
offset
class angr.sim_variable.SimStackVariablePhi(ident=None, name=None, region=None, variables=None)

Bases: angr.sim_variable.SimStackVariable

variables
phi
class angr.sim_variable.SimVariableSet

Bases: collections.abc.MutableSet

A collection of SimVariables.

add(item)
add_register_variable(reg_var)
add_memory_variable(mem_var)
discard(item)
discard_register_variable(reg_var)
discard_memory_variable(mem_var)
add_memory_variables(addrs, size)
copy()
complement(other)

Calculate the complement of self and other.

Parameters:other – Another SimVariableSet instance.
Returns:The complement result.
contains_register_variable(reg_var)
contains_memory_variable(mem_var)
class angr.sim_type.SimType(label=None)

Bases: object

SimType exists to track type information for SimProcedures.

Parameters:label – the type label.
base = True
name
size

The size of the type in bits.

alignment

The alignment of the type in bytes.

with_arch(arch)
class angr.sim_type.SimTypeBottom(label=None)

Bases: angr.sim_type.SimType

SimTypeBottom basically repesents a type error.

Parameters:label – the type label.
class angr.sim_type.SimTypeTop(size=None, label=None)

Bases: angr.sim_type.SimType

SimTypeTop represents any type (mostly used with a pointer for void*).

class angr.sim_type.SimTypeReg(size, label=None)

Bases: angr.sim_type.SimType

SimTypeReg is the base type for all types that are register-sized.

Parameters:
  • label – the type label.
  • size – the size of the type (e.g. 32bit, 8bit, etc.).
extract(state, addr, concrete=False)
store(state, addr, value)
class angr.sim_type.SimTypeNum(size, signed=True, label=None)

Bases: angr.sim_type.SimType

SimTypeNum is a numeric type of arbitrary length

Parameters:
  • size – The size of the integer, in bytes
  • signed – Whether the integer is signed or not
  • label – A label for the type
extract(state, addr, concrete=False)
store(state, addr, value)
class angr.sim_type.SimTypeInt(signed=True, label=None)

Bases: angr.sim_type.SimTypeReg

SimTypeInt is a type that specifies a signed or unsigned C integer.

Parameters:
  • signed – True if signed, False if unsigned
  • label – The type label
size
extract(state, addr, concrete=False)
class angr.sim_type.SimTypeShort(signed=True, label=None)

Bases: angr.sim_type.SimTypeInt

Parameters:
  • signed – True if signed, False if unsigned
  • label – The type label
class angr.sim_type.SimTypeLong(signed=True, label=None)

Bases: angr.sim_type.SimTypeInt

Parameters:
  • signed – True if signed, False if unsigned
  • label – The type label
class angr.sim_type.SimTypeLongLong(signed=True, label=None)

Bases: angr.sim_type.SimTypeInt

Parameters:
  • signed – True if signed, False if unsigned
  • label – The type label
class angr.sim_type.SimTypeChar(label=None)

Bases: angr.sim_type.SimTypeReg

SimTypeChar is a type that specifies a character; this could be represented by a byte, but this is meant to be interpreted as a character.

Parameters:label – the type label.
store(state, addr, value)
extract(state, addr, concrete=False)
class angr.sim_type.SimTypeBool(label=None)

Bases: angr.sim_type.SimTypeChar

Parameters:label – the type label.
store(state, addr, value)
extract(state, addr, concrete=False)
class angr.sim_type.SimTypeFd(label=None)

Bases: angr.sim_type.SimTypeReg

SimTypeFd is a type that specifies a file descriptor.

Parameters:label – the type label
class angr.sim_type.SimTypePointer(pts_to, label=None, offset=0)

Bases: angr.sim_type.SimTypeReg

SimTypePointer is a type that specifies a pointer to some other type.

Parameters:
  • label – The type label.
  • pts_to – The type to which this pointer points to.
make(pts_to)
size
class angr.sim_type.SimTypeFixedSizeArray(elem_type, length)

Bases: angr.sim_type.SimType

SimTypeFixedSizeArray is a literal (i.e. not a pointer) fixed-size array.

extract(state, addr, concrete=False)
store(state, addr, values)
size
alignment
class angr.sim_type.SimTypeArray(elem_type, length=None, label=None)

Bases: angr.sim_type.SimType

SimTypeArray is a type that specifies a pointer to an array; while it is a pointer, it has a semantic difference.

Parameters:
  • label – The type label.
  • elem_type – The type of each element in the array.
  • length – An expression of the length of the array, if known.
size
alignment
class angr.sim_type.SimTypeString(length=None, label=None)

Bases: angr.sim_type.SimTypeArray

SimTypeString is a type that represents a C-style string, i.e. a NUL-terminated array of bytes.

Parameters:
  • label – The type label.
  • length – An expression of the length of the string, if known.
extract(state, addr, concrete=False)
size
alignment
class angr.sim_type.SimTypeWString(length=None, label=None)

Bases: angr.sim_type.SimTypeArray

A wide-character null-terminated string, where each character is 2 bytes.

extract(state, addr, concrete=False)
size
alignment
class angr.sim_type.SimTypeFunction(args, returnty, label=None)

Bases: angr.sim_type.SimType

SimTypeFunction is a type that specifies an actual function (i.e. not a pointer) with certain types of arguments and a certain return value.

Parameters:
  • label – The type label
  • args – A tuple of types representing the arguments to the function
  • returnty – The return type of the function, or none for void
base = False
size
class angr.sim_type.SimTypeLength(signed=False, addr=None, length=None, label=None)

Bases: angr.sim_type.SimTypeLong

SimTypeLength is a type that specifies the length of some buffer in memory.

…I’m not really sure what the original design of this class was going for

Parameters:
  • signed – Whether the value is signed or not
  • label – The type label.
  • addr – The memory address (expression).
  • length – The length (expression).
size
class angr.sim_type.SimTypeFloat(size=32)

Bases: angr.sim_type.SimTypeReg

An IEEE754 single-precision floating point number

sort = FLOAT
signed = True
extract(state, addr, concrete=False)
store(state, addr, value)
class angr.sim_type.SimTypeDouble(align_double=True)

Bases: angr.sim_type.SimTypeFloat

An IEEE754 double-precision floating point number

sort = DOUBLE
alignment
class angr.sim_type.SimStruct(fields, name=None, pack=False, align=None)

Bases: angr.sim_type.SimType

name
offsets
extract(state, addr, concrete=False)
size
alignment
store(state, addr, value)
class angr.sim_type.SimStructValue(struct, values=None)

Bases: object

A SimStruct type paired with some real values

Parameters:
  • struct – A SimStruct instance describing the type of this struct
  • values – A mapping from struct fields to values
class angr.sim_type.SimUnion(members, label=None)

Bases: angr.sim_type.SimType

why

Parameters:members – The members of the struct, as a mapping name -> type
size
alignment
angr.sim_type.make_preamble()
angr.sim_type.define_struct(defn)

Register a struct definition globally

>>> define_struct('struct abcd {int x; int y;}')
angr.sim_type.register_types(mapping)

Pass in a mapping from name to SimType and they will be registered to the global type store

>>> register_types(parse_types("typedef int x; typedef float y;"))
angr.sim_type.do_preprocess(defn)

Run a string through the C preprocessor that ships with pycparser but is weirdly inaccessible?

angr.sim_type.parse_defns(defn, preprocess=True)

Parse a series of C definitions, returns a mapping from variable name to variable type object

angr.sim_type.parse_types(defn, preprocess=True)

Parse a series of C definitions, returns a mapping from type name to type object

angr.sim_type.parse_file(defn, preprocess=True)

Parse a series of C definitions, returns a tuple of two type mappings, one for variable definitions and one for type definitions.

angr.sim_type.parse_type(defn, preprocess=True)

Parse a simple type expression into a SimType

>>> parse_type('int *')
class angr.type_backend.TypedValue(ty, value)

Bases: claripy.backend_object.BackendObject

class angr.type_backend.TypeBackend

Bases: claripy.backends.Backend

apply_annotation(obj, a)
static default_op(expr)
class angr.type_backend.TypeAnnotation(ty)

Bases: claripy.annotation.Annotation

eliminatable
relocatable
class angr.callable.Callable(project, addr, concrete_only=False, perform_merge=True, base_state=None, toc=None, cc=None)

Bases: object

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

If you set perform_merge=True (the default), the result will be returned to you, and you can get the result state with callable.result_state.

Otherwise, you can get the resulting simulation manager at callable.result_path_group.

Parameters:
  • project – The project to operate on
  • addr – The address of the function to use

The following parameters are optional:

Parameters:
  • concrete_only – Throw an exception if the execution splits into multiple paths
  • 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
set_base_state(state)

Swap out the state you’d like to use to perform the call :param state: The state to use to perform the call

perform_call(*args)
call_c(c_args)

Call this Callable with a string of C-style arguments.

Parameters:c_args (str) – C-style arguments.
Returns:The return value from the call.
Return type:claripy.Ast

Knowledge Base

Representing the artifacts of a project.

class angr.knowledge_base.KnowledgeBase(project, obj)

Bases: object

Represents a “model” of knowledge about an artifact.

Contains things like a CFG, data references, etc.

callgraph
unresolved_indirect_jumps
resolved_indirect_jumps
has_plugin(name)
get_plugin(name)
register_plugin(name, plugin)
release_plugin(name)
class angr.knowledge_plugins.plugin.KnowledgeBasePlugin

Bases: object

copy()
static register_default(name, cls)
class angr.knowledge_plugins.comments.Comments(kb)

Bases: angr.knowledge_plugins.plugin.KnowledgeBasePlugin, dict

copy()
class angr.knowledge_plugins.data.Data(kb)

Bases: angr.knowledge_plugins.plugin.KnowledgeBasePlugin

copy()
class angr.knowledge_plugins.indirect_jumps.IndirectJumps(kb)

Bases: angr.knowledge_plugins.plugin.KnowledgeBasePlugin, dict

copy()
class angr.knowledge_plugins.labels.Labels(kb)

Bases: angr.knowledge_plugins.plugin.KnowledgeBasePlugin

get(addr)

Get a label as string for a given address Same as .labels[x]

lookup(name)

Returns an address to a given label To show all available labels, iterate over .labels or list(b.kb.labels)

copy()
class angr.knowledge_plugins.functions.function_manager.FunctionDict(backref, *args, **kwargs)

Bases: sortedcontainers.sorteddict.SortedDict

FunctionDict is a dict where the keys are function starting addresses and map to the associated Function.

get(addr)
floor_addr(addr)
ceiling_addr(addr)
class angr.knowledge_plugins.functions.function_manager.FunctionManager(kb)

Bases: angr.knowledge_plugins.plugin.KnowledgeBasePlugin, collections.abc.Mapping

This is a function boundaries management tool. It takes in intermediate results during CFG generation, and manages a function map of the binary.

copy()
clear()
get_by_addr(addr)
contains_addr(addr)

Decide if an address is handled by the function manager.

Note: this function is non-conformant with python programming idioms, but its needed for performance reasons.

Parameters:addr (int) – Address of the function.
ceiling_func(addr)

Return the function who has the least address that is greater than or equal to addr.

Parameters:addr (int) – The address to query.
Returns:A Function instance, or None if there is no other function after addr.
Return type:Function or None
floor_func(addr)

Return the function who has the greatest address that is less than or equal to addr.

Parameters:addr (int) – The address to query.
Returns:A Function instance, or None if there is no other function before addr.
Return type:Function or None
function(addr=None, name=None, create=False, syscall=False, plt=None)

Get a function object from the function manager.

Pass either addr or name with the appropriate values.

Parameters:
  • addr (int) – Address of the function.
  • name (str) – Name of the function.
  • create (bool) – Whether to create the function or not if the function does not exist.
  • syscall (bool) – True to create the function as a syscall, False otherwise.
  • or None plt (bool) – True to find the PLT stub, False to find a non-PLT stub, None to disable this restriction.
Returns:

The Function instance, or None if the function is not found and create is False.

Return type:

Function or None

dbg_draw(prefix='dbg_function_')
class angr.knowledge_plugins.functions.function.Function(function_manager, addr, name=None, syscall=None)

Bases: object

A representation of a function and various information about it.

Function constructor

Parameters:
  • addr – The address of the function.
  • name – (Optional) The name of the function.
  • syscall – (Optional) Whether this function is a syscall or not.
transition_graph
normalized
addr
is_syscall
is_simprocedure
is_plt
binary_name
bp_on_stack
retaddr_on_stack
sp_delta
calling_convention
prototype
prepared_registers
prepared_stack_variables
registers_read_afterwards
startpoint
info
tags
name
returning
blocks

An iterator of all local blocks in the current function.

Returns:angr.lifter.Block instances.
block_addrs

An iterator of all local block addresses in the current function.

Returns:block addresses.
block_addrs_set

Return a set of block addresses for a better performance of inclusion tests.

Returns:A set of block addresses.
Return type:set
nodes
get_node(addr)
has_unresolved_jumps
has_unresolved_calls
operations

All of the operations that are done by this functions.

code_constants

All of the constants that are used by this functions’s code.

string_references(minimum_length=2, vex_only=False)

All of the constant string references used by this function.

Parameters:
  • minimum_length – The minimum length of strings to find (default is 1)
  • vex_only – Only analyze VEX IR, don’t interpret the entry state to detect additional constants.
Returns:

A list of tuples of (address, string) where is address is the location of the string in memory.

local_runtime_values

Tries to find all runtime values of this function which do not come from inputs. These values are generated by starting from a blank state and reanalyzing the basic blocks once each. Function calls are skipped, and back edges are never taken so these values are often unreliable, This function is good at finding simple constant addresses which the function will use or calculate.

Returns:a set of constants
runtime_values

All of the concrete values used by this function at runtime (i.e., including passed-in arguments and global values).

num_arguments
endpoints
endpoints_with_type
ret_sites
jumpout_sites
retout_sites
callout_sites
size
binary

Get the object this function belongs to. :return: The object this function belongs to.

add_jumpout_site(node)

Add a custom jumpout site.

Parameters:node – The address of the basic block that control flow leaves during this transition.
Returns:None
add_retout_site(node)

Add a custom retout site.

Retout (returning to outside of the function) sites are very rare. It mostly occurs during CFG recovery when we incorrectly identify the beginning of a function in the first iteration, and then correctly identify that function later in the same iteration (function alignments can lead to this bizarre case). We will mark all edges going out of the header of that function as a outside edge, because all successors now belong to the incorrectly-identified function. This identification error will be fixed in the second iteration of CFG recovery. However, we still want to keep track of jumpouts/retouts during the first iteration so other logic in CFG recovery still work.

Parameters:node – The address of the basic block that control flow leaves the current function after a call.
Returns:None
mark_nonreturning_calls_endpoints()

Iterate through all call edges in transition graph. For each call a non-returning function, mark the source basic block as an endpoint.

This method should only be executed once all functions are recovered and analyzed by CFG recovery, so we know whether each function returns or not.

Returns:None
get_call_sites()

Gets a list of all the basic blocks that end in calls.

Returns:A list of the addresses of the blocks that end in calls.
get_call_target(callsite_addr)

Get the target of a call.

Parameters:callsite_addr – The address of a basic block that ends in a call.
Returns:The target of said call, or None if callsite_addr is not a callsite.
get_call_return(callsite_addr)

Get the hypothetical return address of a call.

Parameters:callsite_addr – The address of the basic block that ends in a call.
Returns:The likely return target of said call, or None if callsite_addr is not a callsite.
graph

Return a local transition graph that only contain nodes in current function.

subgraph(ins_addrs)

Generate a sub control flow graph of instruction addresses based on self.graph

Parameters:ins_addrs (iterable) – A collection of instruction addresses that should be included in the subgraph.
Returns:A subgraph.
Return type:networkx.DiGraph
instruction_size(insn_addr)

Get the size of the instruction specified by insn_addr.

Parameters:insn_addr (int) – Address of the instruction
Returns:Size of the instruction in bytes, or None if the instruction is not found.
Return type:int
dbg_print()

Returns a representation of the list of basic blocks in this function.

dbg_draw(filename)

Draw the graph and save it to a PNG file.

arguments
has_return
callable
normalize()

Make sure all basic blocks in the transition graph of this function do not overlap. You will end up with a CFG that IDA Pro generates.

This method does not touch the CFG result. You may call CFG{Emulated, Fast}.normalize() for that matter.

Returns:None
find_declaration()

Find the most likely function declaration from the embedded collection of prototypes, set it to self.prototype, and update self.calling_convention with the declaration.

Returns:None
class angr.knowledge_plugins.variables.variable_access.VariableAccess(variable, access_type, location)

Bases: object

class angr.knowledge_plugins.variables.variable_manager.VariableType

Bases: object

REGISTER = 0
MEMORY = 1
class angr.knowledge_plugins.variables.variable_manager.LiveVariables(register_region, stack_region)

Bases: object

A collection of live variables at a program point.

class angr.knowledge_plugins.variables.variable_manager.VariableManagerInternal(manager, func_addr=None)

Bases: object

Manage variables for a function. It is meant to be used internally by VariableManager.

next_variable_ident(sort)
add_variable(sort, start, variable)
set_variable(sort, start, variable)
write_to(variable, offset, location, overwrite=False)
read_from(variable, offset, location, overwrite=False)
reference_at(variable, offset, location, overwrite=False)
make_phi_node(*variables)
set_live_variables(addr, register_region, stack_region)
find_variables_by_insn(ins_addr, sort)
find_variable_by_stmt(block_addr, stmt_idx, sort)
find_variables_by_stmt(block_addr, stmt_idx, sort)
get_variable_accesses(variable, same_name=False)
get_variables(sort=None, collapse_same_ident=False)

Get a list of variables.

Parameters:
  • or None sort (str) – Sort of the variable to get.
  • collapse_same_ident – Whether variables of the same identifier should be collapsed or not.
Returns:

A list of variables.

Return type:

list

input_variables(exclude_specials=True)

Get all variables that have never been written to.

Returns:A list of variables that are never written to.
assign_variable_names()

Assign default names to all variables.

Returns:None
class angr.knowledge_plugins.variables.variable_manager.VariableManager(kb)

Bases: angr.knowledge_plugins.plugin.KnowledgeBasePlugin

Manage variables.

get_function_manager(func_addr)
initialize_variable_names()
get_variable_accesses(variable, same_name=False)

Get a list of all references to the given variable.

Parameters:
  • variable (SimVariable) – The variable.
  • same_name (bool) – Whether to include all variables with the same variable name, or just based on the variable identifier.
Returns:

All references to the variable.

Return type:

list

copy()
class angr.keyed_region.StoredObject(start, obj, size)

Bases: object

class angr.keyed_region.RegionObject(start, size, objects=None)

Bases: object

Represents one or more objects occupying one or more bytes in KeyedRegion.

is_empty
end
internal_objects
includes(offset)
split(split_at)
add_object(obj)
set_object(obj)
copy()
class angr.keyed_region.KeyedRegion(tree=None)

Bases: object

KeyedRegion keeps a mapping between stack offsets and all objects covering that offset. It assumes no variable in this region overlap with another variable in this region.

Registers and function frames can all be viewed as a keyed region.

copy()
merge(other, make_phi_func=None)

Merge another KeyedRegion into this KeyedRegion.

Parameters:other (KeyedRegion) – The other instance to merge with.
Returns:None
dbg_repr()

Get a debugging representation of this keyed region. :return: A string of debugging output.

add_variable(start, variable)

Add a variable to this region at the given offset.

Parameters:
Returns:

None

add_object(start, obj, object_size)

Add/Store an object to this region at the given offset.

Parameters:
  • start
  • obj
  • object_size (int) – Size of the object
Returns:

set_variable(start, variable)

Add a variable to this region at the given offset, and remove all other variables that are fully covered by this variable.

Parameters:
Returns:

None

set_object(start, obj, object_size)

Add an object to this region at the given offset, and remove all other objects that are fully covered by this object.

Parameters:
  • start
  • obj
  • object_size
Returns:

get_base_addr(addr)

Get the base offset (the key we are using to index objects covering the given offset) of a specific offset.

Parameters:addr (int) –
Returns:
Return type:int or None
get_variables_by_offset(start)

Find variables covering the given region offset.

Parameters:start (int) –
Returns:A list of stack variables.
Return type:set
get_objects_by_offset(start)

Find objects covering the given region offset.

Parameters:start
Returns:

Analysis

angr.analyses.register_analysis(cls, name)
class angr.analyses.analysis.AnalysisLogEntry(message, exc_info=False)

Bases: object

class angr.analyses.analysis.AnalysesHub(project)

Bases: angr.misc.plugins.PluginVendor

This class contains functions for all the registered and runnable analyses,

reload_analyses(**kwargs)
class angr.analyses.analysis.AnalysisFactory(project, analysis_cls)

Bases: object

class angr.analyses.analysis.Analysis

Bases: object

This class represents an analysis on the program.

Variables:
  • project – The project for this analysis.
  • kb (KnowledgeBase) – The knowledgebase object.
  • _progress_callback – A callback function for receiving the progress of this analysis. It only takes one argument, which is a float number from 0.0 to 100.0 indicating the current progress.
  • _show_progressbar (bool) – If a progressbar should be shown during the analysis. It’s independent from _progress_callback.
  • _progressbar (progressbar.ProgressBar) – The progress bar object.
project = None
kb = None
errors = []
named_errors = {}
class angr.analyses.forward_analysis.GraphVisitor

Bases: object

A graph visitor takes a node in the graph and returns its successors. Typically it visits a control flow graph, and returns successors of a CFGNode each time. This is the base class of all graph visitors.

startpoints()

Get all start points to begin the traversal.

Returns:A list of startpoints that the traversal should begin with.
successors(node)

Get successors of a node. The node should be in the graph.

Parameters:node – The node to work with.
Returns:A list of successors.
Return type:list
predecessors(node)

Get predecessors of a node. The node should be in the graph.

Parameters:node – The node to work with.
Returns:A list of predecessors.
Return type:list
sort_nodes(nodes=None)

Get a list of all nodes sorted in an optimal traversal order.

Parameters:nodes (iterable) – A collection of nodes to sort. If none, all nodes in the graph will be used to sort.
Returns:A list of sorted nodes.
Return type:list
nodes()

Return an iterator of nodes following an optimal traversal order.

Returns:
nodes_iter(**kwargs)
reset()

Reset the internal node traversal state. Must be called prior to visiting future nodes.

Returns:None
next_node()

Get the next node to visit.

Returns:A node in the graph.
all_successors(node, skip_reached_fixedpoint=False)

Returns all successors to the specific node.

Parameters:node – A node in the graph.
Returns:A set of nodes that are all successors to the given node.
Return type:set
revisit(node, include_self=True)

Revisit a node in the future. As a result, the successors to this node will be revisited as well.

Parameters:node – The node to revisit in the future.
Returns:None
reached_fixedpoint(node)

Mark a node as reached fixed-point. This node as well as all its successors will not be visited in the future.

Parameters:node – The node to mark as reached fixed-point.
Returns:None
class angr.analyses.forward_analysis.FunctionGraphVisitor(func, graph=None)

Bases: angr.analyses.forward_analysis.GraphVisitor

Parameters:func (knowledge.Function) –
startpoints()
successors(node)
predecessors(node)
sort_nodes(nodes=None)
class angr.analyses.forward_analysis.CallGraphVisitor(callgraph)

Bases: angr.analyses.forward_analysis.GraphVisitor

Parameters:callgraph (networkx.DiGraph) –
startpoints()
successors(node)
predecessors(node)
sort_nodes(nodes=None)
class angr.analyses.forward_analysis.SingleNodeGraphVisitor(node)

Bases: angr.analyses.forward_analysis.GraphVisitor

Parameters:node – The single node that should be in the graph.
startpoints()
successors(node)
predecessors(node)
sort_nodes(nodes=None)
class angr.analyses.forward_analysis.JobInfo(key, job)

Bases: object

Stores information of each job.

job

Get the latest available job.

Returns:The latest available job.
merged_jobs
widened_jobs
add_job(job, merged=False, widened=False)

Appended a new job to this JobInfo node. :param job: The new job to append. :param bool merged: Whether it is a merged job or not. :param bool widened: Whether it is a widened job or not.

class angr.analyses.forward_analysis.ForwardAnalysis(order_jobs=False, allow_merging=False, allow_widening=False, status_callback=None, graph_visitor=None)

Bases: object

This is my very first attempt to build a static forward analysis framework that can serve as the base of multiple static analyses in angr, including CFG analysis, VFG analysis, DDG, etc.

In short, ForwardAnalysis performs a forward data-flow analysis by traversing a graph, compute on abstract values, and store results in abstract states. The user can specify what graph to traverse, how a graph should be traversed, how abstract values and abstract states are defined, etc.

ForwardAnalysis has a few options to toggle, making it suitable to be the base class of several different styles of forward data-flow analysis implementations.

ForwardAnalysis supports a special mode when no graph is available for traversal (for example, when a CFG is being initialized and constructed, no other graph can be used). In that case, the graph traversal functionality is disabled, and the optimal graph traversal order is not guaranteed. The user can provide a job sorting method to sort the jobs in queue and optimize traversal order.

Feel free to discuss with me (Fish) if you have any suggestions or complaints.

Constructor

Parameters:
  • order_jobs (bool) – If all jobs should be ordered or not.
  • allow_merging (bool) – If job merging is allowed.
  • allow_widening (bool) – If job widening is allowed.
  • graph_visitor (GraphVisitor or None) – A graph visitor to provide successors.
Returns:

None

should_abort

Should the analysis be terminated. :return: True/False

graph
jobs
abort()

Abort the analysis :return: None

has_job(job)

Checks whether there exists another job which has the same job key. :param job: The job to check.

Returns:True if there exists another job with the same key, False otherwise.
class angr.analyses.backward_slice.BackwardSlice(cfg, cdg, ddg, targets=None, cfg_node=None, stmt_id=None, control_flow_slice=False, same_function=False, no_construct=False)

Bases: angr.analyses.analysis.Analysis

Represents a backward slice of the program.

Create a backward slice from a specific statement based on provided control flow graph (CFG), control dependence graph (CDG), and data dependence graph (DDG).

The data dependence graph can be either CFG-based, or Value-set analysis based. A CFG-based DDG is much faster to generate, but it only reflects those states while generating the CFG, and it is neither sound nor accurate. The VSA based DDG (called VSA_DDG) is based on static analysis, which gives you a much better result.

Parameters:
  • cfg – The control flow graph.
  • cdg – The control dependence graph.
  • ddg – The data dependence graph.
  • targets – A list of “target” that specify targets of the backward slices. Each target can be a tuple in form of (cfg_node, stmt_idx), or a CodeLocation instance.
  • cfg_node – Deprecated. The target CFGNode to reach. It should exist in the CFG.
  • stmt_id – Deprecated. The target statement to reach.
  • control_flow_slice – True/False, indicates whether we should slice only based on CFG. Sometimes when acquiring DDG is difficult or impossible, you can just create a slice on your CFG. Well, if you don’t even have a CFG, then…
  • no_construct – Only used for testing and debugging to easily create a BackwardSlice object.
dbg_repr(max_display=10)

Debugging output of this slice.

Parameters:max_display – The maximum number of SimRun slices to show.
Returns:A string representation.
dbg_repr_run(run_addr)

Debugging output of a single SimRun slice.

Parameters:run_addr – Address of the SimRun.
Returns:A string representation.
annotated_cfg(start_point=None)

Returns an AnnotatedCFG based on slicing result.

Query in taint graph to check if a specific taint will taint the IP in the future or not. The taint is specified with the tuple (simrun_addr, stmt_idx, taint_type).

Parameters:
  • simrun_addr – Address of the SimRun.
  • stmt_idx – Statement ID.
  • taint_type – Type of the taint, might be one of the following: ‘reg’, ‘tmp’, ‘mem’.
  • simrun_whitelist – A list of SimRun addresses that are whitelisted, i.e. the tainted exit will be ignored if it is in those SimRuns.
Returns:

True/False

is_taint_impacting_stack_pointers(simrun_addr, stmt_idx, taint_type, simrun_whitelist=None)

Query in taint graph to check if a specific taint will taint the stack pointer in the future or not. The taint is specified with the tuple (simrun_addr, stmt_idx, taint_type).

Parameters:
  • simrun_addr – Address of the SimRun.
  • stmt_idx – Statement ID.
  • taint_type – Type of the taint, might be one of the following: ‘reg’, ‘tmp’, ‘mem’.
  • simrun_whitelist – A list of SimRun addresses that are whitelisted.
Returns:

True/False.

exception angr.analyses.bindiff.UnmatchedStatementsException

Bases: Exception

class angr.analyses.bindiff.Difference(diff_type, value_a, value_b)

Bases: object

class angr.analyses.bindiff.ConstantChange(offset, value_a, value_b)

Bases: object

angr.analyses.bindiff.differing_constants(block_a, block_b)

Compares two basic blocks and finds all the constants that differ from the first block to the second.

Parameters:
  • block_a – The first block to compare.
  • block_b – The second block to compare.
Returns:

Returns a list of differing constants in the form of ConstantChange, which has the offset in the block and the respective constants.

angr.analyses.bindiff.compare_statement_dict(statement_1, statement_2)
class angr.analyses.bindiff.NormalizedBlock(block, function)

Bases: object

class angr.analyses.bindiff.NormalizedFunction(function)

Bases: object

class angr.analyses.bindiff.FunctionDiff(function_a, function_b, bindiff=None)

Bases: object

This class computes the a diff between two functions.

Parameters:
  • function_a – The first angr Function object to diff.
  • function_b – The second angr Function object.
  • bindiff – An optional Bindiff object. Used for some extra normalization during basic block comparison.
probably_identical

Whether or not these two functions are identical.

Type:returns
identical_blocks

A list of block matches which appear to be identical

Type:returns
differing_blocks

A list of block matches which appear to differ

Type:returns
blocks_with_differing_constants

A list of block matches which appear to differ

Type:return
block_matches
unmatched_blocks
static get_normalized_block(addr, function)
Parameters:
  • addr – Where to start the normalized block.
  • function – A function containing the block address.
Returns:

A normalized basic block.

block_similarity(block_a, block_b)
Parameters:
  • block_a – The first block address.
  • block_b – The second block address.
Returns:

The similarity of the basic blocks, normalized for the base address of the block and function call addresses.

blocks_probably_identical(block_a, block_b, check_constants=False)
Parameters:
  • block_a – The first block address.
  • block_b – The second block address.
  • check_constants – Whether or not to require matching constants in blocks.
Returns:

Whether or not the blocks appear to be identical.

class angr.analyses.bindiff.BinDiff(other_project, enable_advanced_backward_slicing=False, cfg_a=None, cfg_b=None)

Bases: angr.analyses.analysis.Analysis

This class computes the a diff between two binaries represented by angr Projects

Parameters:other_project – The second project to diff
functions_probably_identical(func_a_addr, func_b_addr, check_consts=False)

Compare two functions and return True if they appear identical.

Parameters:
  • func_a_addr – The address of the first function (in the first binary).
  • func_b_addr – The address of the second function (in the second binary).
Returns:

Whether or not the functions appear to be identical.

identical_functions

A list of function matches that appear to be identical

Type:returns
differing_functions

A list of function matches that appear to differ

Type:returns
differing_functions_with_consts()
Returns:A list of function matches that appear to differ including just by constants
differing_blocks

A list of block matches that appear to differ

Type:returns
identical_blocks

return A list of all block matches that appear to be identical

blocks_with_differing_constants

A dict of block matches with differing constants to the tuple of constants

Type:return
unmatched_functions
get_function_diff(function_addr_a, function_addr_b)
Parameters:
  • function_addr_a – The address of the first function (in the first binary)
  • function_addr_b – The address of the second function (in the second binary)
Returns:

the FunctionDiff of the two functions

class angr.analyses.boyscout.BoyScout(cookiesize=1)

Bases: angr.analyses.analysis.Analysis

Try to determine the architecture and endieness of a binary blob

class angr.analyses.calling_convention.CallingConventionAnalysis(func)

Bases: angr.analyses.analysis.Analysis

Analyze the calling convention of functions.

The calling convention of a function can be inferred at both its call sites and the function itself. At call sites, we consider all register and stack variables that are not alive after the function call as parameters to this function. In the function itself, we consider all register and stack variables that are read but without initialization as parameters. Then we synthesize the information from both locations and make a reasonable inference of calling convention of this function.

static recover_calling_conventions(project, kb=None)
Returns:
class angr.analyses.cfg.cfb.CFBlanketView(cfb)

Bases: object

A view into the control-flow blanket.

class angr.analyses.cfg.cfb.Unknown(addr, size, bytes_=None, object_=None, segment=None, section=None)

Bases: object

class angr.analyses.cfg.cfb.CFBlanket(cfg=None)

Bases: angr.analyses.analysis.Analysis

A Control-Flow Blanket is a representation for storing all instructions, data entries, and bytes of a full program.

floor_addr(addr)
floor_item(addr)
floor_items<