API Reference

Project

angr.project.load_shellcode(shellcode, arch, start_offset=0, load_address=0, thumb=False, **kwargs)

Load a new project based on a snippet of assembly or bytecode.

Parameters:

• shellcode – The data to load, as either a bytestring of instructions or a string of assembly text

• 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)

• thumb – Whether this is ARM Thumb shellcode

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, engine=None, load_options=None, translation_cache=True, selfmodifying_code=False, support_selfmodifying_code=None, store_function=None, load_function=None, analyses_preset=None, concrete_target=None, eager_ifunc_resolution=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.

• arch (Arch) –

• load_options (Dict[str, Any]) –

• selfmodifying_code (bool) –

• support_selfmodifying_code (bool | None) –

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.

• engine – The SimEngine class to use for this project.

• translation_cache (bool) – If True, cache translated basic blocks rather than re-translating them.

• 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).

• load_options (Dict[str, Any]) –

• support_selfmodifying_code (bool | None) –

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.

Parameters:

• arch (Arch) –

• load_options (Dict[str, Any]) –

• selfmodifying_code (bool) –

• support_selfmodifying_code (bool | None) –

__init__(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, engine=None, load_options=None, translation_cache=True, selfmodifying_code=False, support_selfmodifying_code=None, store_function=None, load_function=None, analyses_preset=None, concrete_target=None, eager_ifunc_resolution=None, **kwargs)

Parameters:

• load_options (Dict[str, Any] | None) –

• selfmodifying_code (bool) –

• support_selfmodifying_code (bool | None) –

arch: Arch

analyses: AnalysesHubWithDefault

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.

Return type:

bool

Returns:

True if addr is hooked, False otherwise.

hooked_by(addr)

Returns the current hook for addr.

Parameters:

addr – An address.

Return type:

Optional[SimProcedure]

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

symbol_hooked_by(symbol_name)

Return the SimProcedure, if it exists, for the given symbol name.

Parameters:

symbol_name (str) – Name of the symbol.

Return type:

Optional[SimProcedure]

Returns:

None if the address is not hooked.

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.

rehook_symbol(new_address, symbol_name, stubs_on_sync)

Move the hook for a symbol to a specific address :type new_address: :param new_address: the new address that will trigger the SimProc execution :type symbol_name: :param symbol_name: the name of the symbol (f.i. strcmp ) :return: None

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, default_engine=None)

Bases: object

This factory provides access to important analysis elements.

__init__(project, default_engine=None)

snippet(addr, jumpkind=None, **block_opts)

successors(*args, engine=None, **kwargs)

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

Parameters:

• state – The state to analyze

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

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

• jumpkind – optional, the jumpkind of the previous exit

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

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

blank_state(**kwargs)

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

Parameters:

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

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

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

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

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

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

Returns:

The blank state.

Return type:

SimState

entry_state(**kwargs)

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

Parameters:

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

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

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

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

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

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

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

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

Returns:

The entry state.

Return type:

SimState

full_init_state(**kwargs)

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

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

call_state(addr, *args, **kwargs)

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

Parameters:

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

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

The following parameters 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 (Union[List[SimState], SimState, None]) – What to put in the new SimulationManager’s active stash (either a SimState or a list of SimStates).

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

Returns:

The new SimulationManager

Return type:

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, prototype=None, 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

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

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

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

• base_state – The state from which to do these runs

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

• cc – The SimCC to use for a calling convention

Returns:

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

Return type:

angr.callable.Callable

cc()

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

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

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

function_prototype()

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

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

fresh_block(addr, size, backup_state=None)

class angr.block.DisassemblerBlock(addr, insns, thumb, arch)

Bases: object

Helper class to represent a block of dissassembled target architecture instructions

__init__(addr, insns, thumb, arch)

addr

insns

thumb

arch

pp()

class angr.block.DisassemblerInsn

Bases: object

Helper class to represent a disassembled target architecture instruction

property size: int

property address: int

property mnemonic: str

property op_str: str

class angr.block.CapstoneBlock(addr, insns, thumb, arch)

Bases: DisassemblerBlock

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

__init__(addr, insns, thumb, arch)

addr

arch

insns

pp()

thumb

class angr.block.CapstoneInsn(capstone_insn)

Bases: DisassemblerInsn

Represents a capstone instruction.

__init__(capstone_insn)

insn

property size: int

property address: int

property mnemonic: str

property op_str: str

class angr.block.Block(addr, project=None, arch=None, size=None, byte_string=None, vex=None, thumb=False, backup_state=None, extra_stop_points=None, opt_level=None, num_inst=None, traceflags=0, strict_block_end=None, collect_data_refs=False, cross_insn_opt=True, load_from_ro_regions=False, initial_regs=None)

Bases: Serializable

Represents a basic block in a binary or a program.

BLOCK_MAX_SIZE = 4096

__init__(addr, project=None, arch=None, size=None, byte_string=None, vex=None, thumb=False, backup_state=None, extra_stop_points=None, opt_level=None, num_inst=None, traceflags=0, strict_block_end=None, collect_data_refs=False, cross_insn_opt=True, load_from_ro_regions=False, initial_regs=None)

arch

thumb

addr

size

pp(**kwargs)

set_initial_regs()

static reset_initial_regs()

property vex: IRSB

property vex_nostmt

property disassembly: DisassemblerBlock

Provide a disassembly object using whatever disassembler is available

property capstone

property codenode

property bytes

property instructions

property instruction_addrs

serialize_to_cmessage()

Serialize the class object and returns a protobuf cmessage object.

Returns:

A protobuf cmessage object.

Return type:

protobuf.cmessage

classmethod parse_from_cmessage(cmsg)

Parse a protobuf cmessage and create a class object.

Parameters:

cmsg – The probobuf cmessage object.

Returns:

A unserialized class object.

Return type:

cls

classmethod parse(s, **kwargs)

Parse a bytes object and create a class object.

Parameters:

s (bytes) – A bytes object.

Returns:

A class object.

Return type:

cls

serialize()

Serialize the class object and returns a bytes object.

Returns:

A bytes object.

Return type:

bytes

class angr.block.SootBlock(addr, project=None, arch=None)

Bases: object

Represents a Soot IR basic block.

__init__(addr, project=None, arch=None)

property soot

property size

property codenode

Plugin Ecosystem

class angr.misc.plugins.PluginHub

Bases: Generic[P]

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.

__init__()

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.

property plugin_preset

Get the current active plugin preset

property has_plugin_preset: bool

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.

Return type:

TypeVar(P)

Parameters:

name (str) –

has_plugin(name)

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

register_plugin(name, plugin)

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

Parameters:

name (str) –

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.

__init__()

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.

Return type:

Type[TypeVar(P)]

Parameters:

name (str) –

copy()

Return a copy of self.

class angr.misc.plugins.PluginVendor

Bases: Generic[P], PluginHub[P]

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)

Deactivate and remove the plugin with name name.

register_plugin(name, plugin)

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

__init__()

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.

Return type:

TypeVar(P)

Parameters:

name (str) –

has_plugin(name)

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

property has_plugin_preset: bool

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

property plugin_preset

Get the current active plugin preset

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.

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.

class angr.misc.plugins.VendorPreset

Bases: PluginPreset

A specialized preset class for use with the PluginVendor.

__init__()

activate(hub)

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

add_default_plugin(name, plugin_cls)

Add a plugin to the preset.

copy()

Return a copy of self.

deactivate(hub)

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

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.

Return type:

Type[TypeVar(P)]

Parameters:

name (str) –

Program State

angr.sim_state.arch_overrideable(f)

class angr.sim_state.SimState(project=None, arch=None, plugins=None, mode=None, options=None, add_options=None, remove_options=None, special_memory_filler=None, os_name=None, plugin_preset='default', cle_memory_backer=None, dict_memory_backer=None, permissions_map=None, default_permissions=3, stack_perms=None, stack_end=None, stack_size=None, regioned_memory_cls=None, **kwargs)

Bases: PluginHub

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

Parameters:

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

• arch (archinfo.Arch|str) – The architecture of the state.

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 – Control of the Unicorn Engine

solver: SimSolver

posix: SimSystemPosix

registers: MemoryMixin

regs: SimRegNameView

memory: MemoryMixin

callstack: CallStack

mem: SimMemView

history: SimStateHistory

inspect: SimInspector

jni_references: SimStateJNIReferences

scratch: SimStateScratch

__init__(project=None, arch=None, plugins=None, mode=None, options=None, add_options=None, remove_options=None, special_memory_filler=None, os_name=None, plugin_preset='default', cle_memory_backer=None, dict_memory_backer=None, permissions_map=None, default_permissions=3, stack_perms=None, stack_end=None, stack_size=None, regioned_memory_cls=None, **kwargs)

property plugins

property se

Deprecated alias for solver

property ip

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

Returns:

an expression

property 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

property arch: Arch

T = ~T

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 currently active.

register_plugin(name, plugin, inhibit_init=False)

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

property javavm_memory

In case of an JavaVM with JNI support, a state can store the memory plugin twice; one for the native and one for the java view of the state.

Returns:

The JavaVM view of the memory plugin.

property javavm_registers

In case of an JavaVM with JNI support, a state can store the registers plugin twice; one for the native and one for the java view of the state.

Returns:

The JavaVM view of the registers plugin.

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 occurred)

widen(*others)

Perform a widening between self and other states :type others: :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)

property thumb

property with_condition

discard_plugin_preset()

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

property has_plugin_preset: bool

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

property plugin_preset

Get the current active plugin preset

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.

release_plugin(name)

Deactivate and remove the plugin with name name.

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.

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

Bases: object

Describes a state option.

__init__(name, types, default='_NO_DEFAULT_VALUE', description=None)

name

types

default

description

property 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).

OPTIONS = {'ABSTRACT_MEMORY': <O ABSTRACT_MEMORY[bool]>, 'ABSTRACT_SOLVER': <O ABSTRACT_SOLVER[bool]>, 'ACTION_DEPS': <O ACTION_DEPS[bool]>, 'ADD_AUTO_REFS': <O ADD_AUTO_REFS[bool]>, 'ALLOW_SEND_FAILURES': <O ALLOW_SEND_FAILURES[bool]>, 'ALL_FILES_EXIST': <O ALL_FILES_EXIST[bool]>, 'ANY_FILE_MIGHT_EXIST': <O ANY_FILE_MIGHT_EXIST[bool]>, 'APPROXIMATE_FIRST': <O APPROXIMATE_FIRST[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]>, 'BYPASS_ERRORED_IRCCALL': <O BYPASS_ERRORED_IRCCALL[bool]>, 'BYPASS_ERRORED_IROP': <O BYPASS_ERRORED_IROP[bool]>, 'BYPASS_ERRORED_IRSTMT': <O BYPASS_ERRORED_IRSTMT[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]>, 'COPY_STATES': <O COPY_STATES[bool]>, 'CPUID_SYMBOLIC': <O CPUID_SYMBOLIC[bool]>, 'DOWNSIZE_Z3': <O DOWNSIZE_Z3[bool]>, 'DO_CCALLS': <O DO_CCALLS[bool]>, 'DO_RET_EMULATION': <O DO_RET_EMULATION[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]>, 'HYBRID_SOLVER': <O HYBRID_SOLVER[bool]>, 'JAVA_IDENTIFY_GETTER_SETTER': <O JAVA_IDENTIFY_GETTER_SETTER[bool]>, 'JAVA_TRACK_ATTRIBUTES': <O JAVA_TRACK_ATTRIBUTES[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_CHUNK_INDIVIDUAL_READS': <O MEMORY_CHUNK_INDIVIDUAL_READS[bool]>, 'MEMORY_FIND_STRICT_SIZE_LIMIT': <O MEMORY_FIND_STRICT_SIZE_LIMIT[bool]>, 'MEMORY_SYMBOLIC_BYTES_MAP': <O MEMORY_SYMBOLIC_BYTES_MAP[bool]>, 'NO_CROSS_INSN_OPT': <O NO_CROSS_INSN_OPT[bool]>, 'NO_IP_CONCRETIZATION': <O NO_IP_CONCRETIZATION[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_MERGED_CONSTRAINTS': <O SIMPLIFY_MERGED_CONSTRAINTS[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]>, 'STRINGS_ANALYSIS': <O STRINGS_ANALYSIS[bool]>, 'SUPER_FASTPATH': <O SUPER_FASTPATH[bool]>, 'SUPPORT_FLOATING_POINT': <O SUPPORT_FLOATING_POINT[bool]>, 'SYMBION_KEEP_STUBS_ON_SYNC': <O SYMBION_KEEP_STUBS_ON_SYNC[bool]>, 'SYMBION_SYNC_CLE': <O SYMBION_SYNC_CLE[bool]>, 'SYMBOLIC': <O SYMBOLIC[bool]>, 'SYMBOLIC_INITIAL_VALUES': <O SYMBOLIC_INITIAL_VALUES[bool]>, 'SYMBOLIC_MEMORY_NO_SINGLEVALUE_OPTIMIZATIONS': <O SYMBOLIC_MEMORY_NO_SINGLEVALUE_OPTIMIZATIONS[bool]>, 'SYMBOLIC_TEMPS': <O SYMBOLIC_TEMPS[bool]>, 'SYMBOLIC_WRITE_ADDRESSES': <O SYMBOLIC_WRITE_ADDRESSES[bool]>, 'SYMBOL_FILL_UNCONSTRAINED_MEMORY': <O SYMBOL_FILL_UNCONSTRAINED_MEMORY[bool]>, 'SYMBOL_FILL_UNCONSTRAINED_REGISTERS': <O SYMBOL_FILL_UNCONSTRAINED_REGISTERS[bool]>, 'SYNC_CLE_BACKEND_CONCRETE': <O SYNC_CLE_BACKEND_CONCRETE[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_CGC_RANDOM_SYSCALL': <O UNICORN_HANDLE_CGC_RANDOM_SYSCALL[bool]>, 'UNICORN_HANDLE_CGC_RECEIVE_SYSCALL': <O UNICORN_HANDLE_CGC_RECEIVE_SYSCALL[bool]>, 'UNICORN_HANDLE_CGC_TRANSMIT_SYSCALL': <O UNICORN_HANDLE_CGC_TRANSMIT_SYSCALL[bool]>, 'UNICORN_HANDLE_SYMBOLIC_ADDRESSES': <O UNICORN_HANDLE_SYMBOLIC_ADDRESSES[bool]>, 'UNICORN_HANDLE_SYMBOLIC_CONDITIONS': <O UNICORN_HANDLE_SYMBOLIC_CONDITIONS[bool]>, 'UNICORN_HANDLE_SYMBOLIC_SYSCALLS': <O UNICORN_HANDLE_SYMBOLIC_SYSCALLS[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]>, 'UNSUPPORTED_FORCE_CONCRETIZE': <O UNSUPPORTED_FORCE_CONCRETIZE[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]>, 'ZERO_FILL_UNCONSTRAINED_REGISTERS': <O ZERO_FILL_UNCONSTRAINED_REGISTERS[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.>}

__init__(thing)

Parameters:

thing – Either a set of Boolean switches to enable, or an existing SimStateOptions instance.

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

__init__()

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

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.

__init__(when='before', enabled=None, condition=None, action=None, **kwargs)

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: SimStatePlugin

The breakpoint interface, used to instrument execution. For usage information, look here: https://docs.angr.io/core-concepts/simulation#breakpoints

BP_AFTER = 'after'

BP_BEFORE = 'before'

BP_BOTH = 'both'

__init__()

action(event_type, when, **kwargs)

Called from within the engine 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)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

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)

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

set_state(state)

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

STRONGREF_STATE = False

init_state()

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

static memo(f)

A decorator function you should apply to copy

classmethod register_default(name, xtr=None)

set_strongref_state(state)

state: angr.SimState

class angr.state_plugins.libc.SimStateLibc

Bases: 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]

__init__()

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

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

property errno

ret_errno(val)

STRONGREF_STATE = False

init_state()

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

static memo(f)

A decorator function you should apply to copy

classmethod register_default(name, xtr=None)

set_state(state)

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

set_strongref_state(state)

state: angr.SimState

class angr.state_plugins.posix.PosixDevFS

Bases: SimMount

get(path)

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, 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 occurred

delete(path)

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 occurred

lookup(_)

Look up the path of a SimFile in the mountpoint

Parameters:

sim_file – A SimFile object needs to be looked up

Returns:

A string representing the path of the file in the mountpoint Or None if the SimFile does not exist in the mountpoint

merge(others, 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

copy(_)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

STRONGREF_STATE = False

__init__()

init_state()

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

static memo(f)

A decorator function you should apply to copy

classmethod register_default(name, xtr=None)

set_state(state)

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

set_strongref_state(state)

state: angr.SimState

class angr.state_plugins.posix.PosixProcFS

Bases: SimMount

The virtual file system mounted at /proc (as of now, on Linux).

get(path)

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, 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 occurred

delete(path)

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 occurred

lookup(_)

Look up the path of a SimFile in the mountpoint

Parameters:

sim_file – A SimFile object needs to be looked up

Returns:

A string representing the path of the file in the mountpoint Or None if the SimFile does not exist in the mountpoint

merge(others, 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

copy(_)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

STRONGREF_STATE = False

__init__()

init_state()

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

static memo(f)

A decorator function you should apply to copy

classmethod register_default(name, xtr=None)

set_state(state)

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

set_strongref_state(state)

state: angr.SimState

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, sigmask=None, pid=None, ppid=None, uid=None, gid=None, brk=None)

Bases: 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

EMLINK = 31

EPIPE = 32

EDOM = 33

ERANGE = 34

__init__(stdin=None, stdout=None, stderr=None, fd=None, sockets=None, socket_queue=None, argv=None, argc=None, environ=None, auxv=None, tls_modules=None, sigmask=None, pid=None, ppid=None, uid=None, gid=None, brk=None)

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

property closed_fds

init_state()

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

set_brk(new_brk)

set_state(state)

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

open(name, flags, preferred_fd=None)

Open a symbolic file. Basically open(2).

Parameters:

• name (string or bytes) – Path of the symbolic file, as a string or bytes.

• 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 -1 if the open fails.

mode from open(2) is unsupported at present.

open_socket(ident)

get_fd(fd, create_file=True)

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. Set create_file to False if no write-access is planned (i.e. fd is read-only).

get_concrete_fd(fd, create_file=True)

Same behavior as get_fd(fd), only the result is a concrete integer fd (or -1) instead of a SimFileDescriptor.

close(fd)

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

fstat(fd)

fstat_with_result(sim_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

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

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

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

STRONGREF_STATE = False

static memo(f)

A decorator function you should apply to copy

classmethod register_default(name, xtr=None)

set_strongref_state(state)

state: angr.SimState

class angr.state_plugins.filesystem.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

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

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

st_nlink

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.filesystem.SimFilesystem(files=None, pathsep=None, cwd=None, mountpoints=None)

Bases: 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.

__init__(files=None, pathsep=None, cwd=None, mountpoints=None)

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

property unlinks

set_state(state)

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

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

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.

STRONGREF_STATE = False

init_state()

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

static memo(f)

A decorator function you should apply to copy

classmethod register_default(name, xtr=None)

set_strongref_state(state)

state: angr.SimState

class angr.state_plugins.filesystem.SimMount

Bases: 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 occurred

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 occurred

lookup(sim_file)

Look up the path of a SimFile in the mountpoint

Parameters:

sim_file – A SimFile object needs to be looked up

Returns:

A string representing the path of the file in the mountpoint Or None if the SimFile does not exist in the mountpoint

STRONGREF_STATE = False

__init__()

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

init_state()

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

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

classmethod register_default(name, xtr=None)

set_state(state)

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

set_strongref_state(state)

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

state: angr.SimState

class angr.state_plugins.filesystem.SimConcreteFilesystem(pathsep='/')

Bases: SimMount

Abstract SimMount allowing the user to import files from some external source into the guest

Parameters:

pathsep (str) – The host path separator character, default os.path.sep

__init__(pathsep='/')

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 occurred

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 occurred

lookup(sim_file)

Look up the path of a SimFile in the mountpoint

Parameters:

sim_file – A SimFile object needs to be looked up

Returns:

A string representing the path of the file in the mountpoint Or None if the SimFile does not exist in the mountpoint

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

set_state(state)

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

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

STRONGREF_STATE = False

init_state()

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

static memo(f)

A decorator function you should apply to copy

classmethod register_default(name, xtr=None)

set_strongref_state(state)

state: angr.SimState

class angr.state_plugins.filesystem.SimHostFilesystem(host_path=None, **kwargs)

Bases: SimConcreteFilesystem

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

__init__(host_path=None, **kwargs)

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

STRONGREF_STATE = False

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 occurred

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

init_state()

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

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 occurred

lookup(sim_file)

Look up the path of a SimFile in the mountpoint

Parameters:

sim_file – A SimFile object needs to be looked up

Returns:

A string representing the path of the file in the mountpoint Or None if the SimFile does not exist in the mountpoint

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

classmethod register_default(name, xtr=None)

set_state(state)

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

set_strongref_state(state)

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

state: angr.SimState

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: 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.

__init__(solver=None, all_variables=None, temporal_tracked_variables=None, eternal_tracked_variables=None)

reload_solver(constraints=None)

Reloads the solver. Useful when changing solver options.

Parameters:

constraints (list) – A new list of constraints to use in the reloaded solver instead of the current one

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)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

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

downsize()

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

property 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, signed=False)

Return the maximum value of expression e.

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

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

Return the minimum value of expression e.

:param e : expression (an AST) to evaluate :type extra_constraints: :param extra_constraints: extra constraints (as ASTs) to add to the solver for this solve :param exact : if False, return approximate solutions. :param signed : Whether the expression should be treated as a signed value. :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.

CastType = ~CastType

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 – desired type of resulting values

Returns:

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

Return type:

tuple

eval(e, cast_to=None, **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

• cast_to – desired type of resulting values

Raises:

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

Returns:

eval_one(e, cast_to=None, **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

• cast_to – desired type of resulting values

• 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

STRONGREF_STATE = False

init_state()

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

static memo(f)

A decorator function you should apply to copy

classmethod register_default(name, xtr=None)

set_state(state)

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

set_strongref_state(state)

state: angr.SimState

eval_atmost(e, n, cast_to=None, **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

• cast_to – desired type of resulting values

• 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, cast_to=None, **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

• cast_to – desired type of resulting values

• 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, cast_to=None, **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

• cast_to – desired type of resulting values

• 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, signed=False)

Return the minimum value of expression e.

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

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

Return the maximum value of expression e.

:param e : expression (an AST) to evaluate :type extra_constraints: :param extra_constraints: extra constraints (as ASTs) to add to the solver for this solve :param exact : if False, return approximate solutions. :param signed : Whether the expression should be treated as a signed value. :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: SimStatePlugin

__init__(log=None)

property actions

add_event(event_type, **kwargs)

add_action(action)

extend_actions(new_actions)

events_of_type(event_type)

actions_of_type(action_type)

property fresh_constraints

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

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

clear()

STRONGREF_STATE = False

init_state()

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

static memo(f)

A decorator function you should apply to copy

classmethod register_default(name, xtr=None)

set_state(state)

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

set_strongref_state(state)

state: angr.SimState

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, invoke_return_variable=None)

Bases: 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.

Parameters:

next_frame (CallStack | None) –

__init__(call_site_addr=0, func_addr=0, stack_ptr=0, ret_addr=0, jumpkind='Ijk_Call', next_frame=None, invoke_return_variable=None)

Parameters:

next_frame (CallStack | None) –

state: angr.SimState

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

set_state(state)

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

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

property current_function_address

Address of the current function.

Returns:

the address of the function

Return type:

int

property current_stack_pointer

Get the value of the stack pointer.

Returns:

Value of the stack pointer

Return type:

int

property 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

property 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

• retn_target (int or None) – 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

STRONGREF_STATE = False

init_state()

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

static memo(f)

A decorator function you should apply to copy

classmethod register_default(name, xtr=None)

set_strongref_state(state)

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.

__init__(callstack_hash, callstack_depth, action, callframe=None, ret_site_addr=None)

class angr.state_plugins.light_registers.SimLightRegisters(reg_map=None, registers=None)

Bases: SimStatePlugin

__init__(reg_map=None, registers=None)

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

set_state(state)

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

resolve_register(offset, size)

load(offset, size=None, **kwargs)

store(offset, value, size=None, endness=None, **kwargs)

STRONGREF_STATE = False

init_state()

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

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

classmethod register_default(name, xtr=None)

set_strongref_state(state)

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

state: angr.SimState

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

Bases: SimStatePlugin

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

STRONGREF_STATE = True

__init__(parent=None, clone=None)

init_state()

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

set_strongref_state(state)

property addr

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

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

trim()

Discard the ancestry of this state.

filter_actions(start_block_addr=None, end_block_addr=None, block_stmt=None, insn_addr=None, read_from=None, write_to=None)

Filter self.actions based on some common parameters.

[start_block_addr, end_block_addr]

Parameters:

• start_block_addr – Only return actions generated in blocks starting at this address.

• end_block_addr – Only return actions generated in blocks ending 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)

subscribe_actions()

property recent_constraints

property recent_actions

property block_count

property lineage

property parents

property events

property actions

property jumpkinds

property jump_guards

property jump_targets

property jump_sources

property descriptions

property bbl_addrs

property ins_addrs

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

static memo(f)

A decorator function you should apply to copy

classmethod register_default(name, xtr=None)

set_state(state)

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

state: angr.SimState

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

Bases: object

__init__(start, end=None)

property 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: TreeIter

__init__(start, end=None)

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

property hardcopy

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

Bases: TreeIter

__init__(start, f, **kwargs)

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

property hardcopy

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

Bases: LambdaAttrIter

__init__(start, f, reverse=True, **kwargs)

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

property hardcopy

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

Bases: SimStatePlugin

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

__init__(omit_fp=False, adjust_stack=False)

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)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

STRONGREF_STATE = False

init_state()

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

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

classmethod register_default(name, xtr=None)

set_state(state)

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

set_strongref_state(state)

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

state: angr.SimState

class angr.state_plugins.cgc.SimStateCGC

Bases: SimStatePlugin

This state plugin keeps track of CGC state.

EBADF = 1

EFAULT = 2

EINVAL = 3

ENOMEM = 4

ENOSYS = 5

EPIPE = 6

FD_SETSIZE = 1024

max_allocation = 268435456

__init__()

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

peek_input()

discard_input(num_bytes)

peek_output()

discard_output(num_bytes)

addr_invalid(a)

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

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.

STRONGREF_STATE = False

init_state()

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

static memo(f)

A decorator function you should apply to copy

classmethod register_default(name, xtr=None)

set_state(state)

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

set_strongref_state(state)

state: angr.SimState

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: FormatInfo

__init__(addr, func_name, str_arg_num, base, base_arg, allows_negative)

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: FormatInfo

__init__(addr, func_name, int_arg_num, str_dst_num, base, base_arg)

copy()

compute(state)

get_type()

class angr.state_plugins.trace_additions.FormatInfoDontConstrain(addr, func_name, check_symbolic_arg)

Bases: FormatInfo

__init__(addr, func_name, check_symbolic_arg)

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: SimStatePlugin

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

__init__()

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

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

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)

STRONGREF_STATE = False

init_state()

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

static memo(f)

A decorator function you should apply to copy

classmethod register_default(name, xtr=None)

set_state(state)

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

set_strongref_state(state)

state: SimState

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: SimStatePlugin

__init__(max_depth=13)

static get_flag_rand_args(expr)

get_expr_depth(expr)

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

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

get_flag_bytes(ast)

filter_constraints(constraints)

analyze_transmit(state, buf)

static prep_tracer(state)

STRONGREF_STATE = False

init_state()

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

static memo(f)

A decorator function you should apply to copy

classmethod register_default(name, xtr=None)

set_state(state)

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

set_strongref_state(state)

state: SimState

class angr.state_plugins.globals.SimStateGlobals(backer=None)

Bases: SimStatePlugin

__init__(backer=None)

set_state(state)

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

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

keys()

values()

items()

get(k, alt=None)

pop(k, alt=None)

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

STRONGREF_STATE = False

init_state()

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

static memo(f)

A decorator function you should apply to copy

classmethod register_default(name, xtr=None)

set_strongref_state(state)

state: angr.SimState

class angr.state_plugins.uc_manager.SimUCManager(man=None)

Bases: SimStatePlugin

__init__(man=None)

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)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

get_alloc_depth(addr)

STRONGREF_STATE = False

init_state()

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

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

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

classmethod register_default(name, xtr=None)

set_strongref_state(state)

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

state: angr.SimState

set_state(state)

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

class angr.state_plugins.scratch.SimStateScratch(scratch=None)

Bases: SimStatePlugin

Implements the scratch state plugin.

__init__(scratch=None)

STRONGREF_STATE = False

init_state()

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

static memo(f)

A decorator function you should apply to copy

classmethod register_default(name, xtr=None)

set_state(state)

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

set_strongref_state(state)

state: angr.SimState

property priv

push_priv(priv)

pop_priv()

set_tyenv(tyenv)

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, deps=None, **kwargs)

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)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

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

clear()

class angr.state_plugins.preconstrainer.SimStatePreconstrainer(constrained_addrs=None)

Bases: SimStatePlugin

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

Parameters:

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

__init__(constrained_addrs=None)

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

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

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)

Remove the preconstraints from the state.

If you are using the zen plugin, this will also use that to filter the constraints.

Parameters:

• to_composite_solver – Whether to convert the replacement solver to a composite solver. You probably want this if you’re switching from tracing to symbolic analysis.

• simplify – Whether to simplify the resulting set of constraints.

reconstrain()

Split the solver. If any of the subsolvers time out after a short timeout (10 seconds), re-add the preconstraints associated with each of its variables. Hopefully these constraints still allow us to do meaningful things to the state.

STRONGREF_STATE = False

init_state()

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

static memo(f)

A decorator function you should apply to copy

classmethod register_default(name, xtr=None)

set_state(state)

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

set_strongref_state(state)

state: angr.SimState

class angr.state_plugins.unicorn_engine.MEM_PATCH

Bases: Structure

struct mem_update_t

__init__(*args, **kwargs)

address

Structure/Union member

length

Structure/Union member

next

Structure/Union member

class angr.state_plugins.unicorn_engine.TRANSMIT_RECORD

Bases: Structure

struct transmit_record_t

__init__(*args, **kwargs)

count

Structure/Union member

data

Structure/Union member

fd

Structure/Union member

class angr.state_plugins.unicorn_engine.TaintEntityEnum

Bases: object

taint_entity_enum_t

TAINT_ENTITY_REG = 0

TAINT_ENTITY_TMP = 1

TAINT_ENTITY_MEM = 2

TAINT_ENTITY_NONE = 3

class angr.state_plugins.unicorn_engine.MemoryValue

Bases: Structure

struct memory_value_t

__init__(*args, **kwargs)

address

Structure/Union member

is_value_set

Structure/Union member

is_value_symbolic

Structure/Union member

value

Structure/Union member

class angr.state_plugins.unicorn_engine.RegisterValue

Bases: Structure

struct register_value_t

__init__(*args, **kwargs)

offset

Structure/Union member

size

Structure/Union member

value

Structure/Union member

class angr.state_plugins.unicorn_engine.VEXStmtDetails

Bases: Structure

struct sym_vex_stmt_details_t

__init__(*args, **kwargs)

has_memory_dep

Structure/Union member

memory_values

Structure/Union member

memory_values_count

Structure/Union member

stmt_idx

Structure/Union member

class angr.state_plugins.unicorn_engine.BlockDetails

Bases: Structure

struct sym_block_details_ret_t

__init__(*args, **kwargs)

block_addr

Structure/Union member

block_size

Structure/Union member

block_trace_ind

Structure/Union member

has_symbolic_exit

Structure/Union member

register_values

Structure/Union member

register_values_count

Structure/Union member

symbolic_vex_stmts

Structure/Union member

symbolic_vex_stmts_count

Structure/Union member

class angr.state_plugins.unicorn_engine.STOP

Bases: object

enum stop_t

STOP_NORMAL = 0

STOP_STOPPOINT = 1

STOP_ERROR = 2

STOP_SYSCALL = 3

STOP_EXECNONE = 4

STOP_ZEROPAGE = 5

STOP_NOSTART = 6

STOP_SEGFAULT = 7

STOP_ZERO_DIV = 8

STOP_NODECODE = 9

STOP_HLT = 10

STOP_VEX_LIFT_FAILED = 11

STOP_SYMBOLIC_PC = 12

STOP_SYMBOLIC_READ_ADDR = 13

STOP_SYMBOLIC_READ_SYMBOLIC_TRACKING_DISABLED = 14

STOP_SYMBOLIC_WRITE_ADDR = 15

STOP_SYMBOLIC_BLOCK_EXIT_CONDITION = 16

STOP_SYMBOLIC_BLOCK_EXIT_TARGET = 17

STOP_UNSUPPORTED_STMT_PUTI = 18

STOP_UNSUPPORTED_STMT_STOREG = 19

STOP_UNSUPPORTED_STMT_LOADG = 20

STOP_UNSUPPORTED_STMT_CAS = 21

STOP_UNSUPPORTED_STMT_LLSC = 22

STOP_UNSUPPORTED_STMT_DIRTY = 23

STOP_UNSUPPORTED_EXPR_GETI = 24

STOP_UNSUPPORTED_STMT_UNKNOWN = 25

STOP_UNSUPPORTED_EXPR_UNKNOWN = 26

STOP_UNKNOWN_MEMORY_WRITE_SIZE = 27

STOP_SYSCALL_ARM = 28

STOP_X86_CPUID = 29

stop_message = {0: 'Reached maximum steps', 1: 'Hit a stop point', 2: 'Something wrong', 3: 'Unable to handle syscall', 4: 'Fetching empty page', 5: 'Accessing zero page', 6: 'Failed to start', 7: 'Permissions or mapping error', 8: 'Divide by zero', 9: 'Instruction decoding error', 10: 'hlt instruction encountered', 11: 'Failed to lift block to VEX', 12: 'Instruction pointer became symbolic', 13: 'Attempted to read from symbolic address', 14: 'Attempted to read symbolic data from memory but symbolic tracking is disabled', 15: 'Attempted to write to symbolic address', 16: "Guard condition of block's exit statement is symbolic", 17: 'Target of default exit of block is symbolic', 18: 'Symbolic taint propagation for PutI statement not yet supported', 19: 'Symbolic taint propagation for StoreG statement not yet supported', 20: 'Symbolic taint propagation for LoadG statement not yet supported', 21: 'Symbolic taint propagation for CAS statement not yet supported', 22: 'Symbolic taint propagation for LLSC statement not yet supported', 23: 'Symbolic taint propagation for Dirty statement not yet supported', 24: 'Symbolic taint propagation for GetI expression not yet supported', 25: 'Canoo propagate symbolic taint for unsupported VEX statement type', 26: 'Cannot propagate symbolic taint for unsupported VEX expression', 27: 'Unicorn failed to determine size of memory write', 28: 'ARM syscalls are currently not supported by SimEngineUnicorn', 29: 'Block executes cpuid which should be handled in VEX engine'}

symbolic_stop_reasons = {12, 13, 14, 15, 16, 17, 28, 29}

unsupported_reasons = {11, 18, 19, 20, 21, 22, 23, 25, 26}

static name_stop(num)

static get_stop_msg(stop_reason)

class angr.state_plugins.unicorn_engine.StopDetails

Bases: Structure

struct stop_details_t

__init__(*args, **kwargs)

block_addr

Structure/Union member

block_size

Structure/Union member

stop_reason

Structure/Union member

class angr.state_plugins.unicorn_engine.SimOSEnum

Bases: object

enum simos_t

SIMOS_CGC = 0

SIMOS_LINUX = 1

SIMOS_OTHER = 2

exception angr.state_plugins.unicorn_engine.MemoryMappingError

Bases: Exception

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.state_plugins.unicorn_engine.AccessingZeroPageError

Bases: MemoryMappingError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.state_plugins.unicorn_engine.FetchingZeroPageError

Bases: MemoryMappingError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.state_plugins.unicorn_engine.SegfaultError

Bases: MemoryMappingError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.state_plugins.unicorn_engine.MixedPermissonsError

Bases: MemoryMappingError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class angr.state_plugins.unicorn_engine.AggressiveConcretizationAnnotation(addr)

Bases: SimplificationAvoidanceAnnotation

__init__(addr)

property eliminatable

Returns whether this annotation can be eliminated in a simplification.

Returns:

True if eliminatable, False otherwise

property relocatable

Returns whether this annotation can be relocated in a simplification.

Returns:

True if it can be relocated, false otherwise.

relocate(src, dst)

This is called when an annotation has to be relocated because of simplifications.

Consider the following case:

x = claripy.BVS(‘x’, 32) zero = claripy.BVV(0, 32).add_annotation(your_annotation) y = x + zero

Here, one of three things can happen:

1. if your_annotation.eliminatable is True, the simplifiers will simply eliminate your_annotation along with zero and y is x will hold

2. elif your_annotation.relocatable is False, the simplifier will abort and y will never be simplified

3. elif your_annotation.relocatable is True, the simplifier will run, determine that the simplified result of x + zero will be x. It will then call your_annotation.relocate(zero, x) to move the annotation away from the AST that is about to be eliminated.

Parameters:

• src – the old AST that was eliminated in the simplification

• dst – the new AST (the result of a simplification)

Returns:

the annotation that will be applied to dst

class angr.state_plugins.unicorn_engine.Uniwrapper(arch, cache_key, thumb=False)

Bases: Uc

__init__(arch, cache_key, thumb=False)

hook_add(htype, callback, user_data=None, begin=1, end=0, arg1=0)

hook_del(h)

mem_map(addr, size, perms=7)

mem_map_ptr(addr, size, perms, ptr)

mem_unmap(addr, size)

mem_reset()

hook_reset()

reset()

context_restore(context)

Parameters:

context (UcContext) –

context_save()

context_update(context)

Parameters:

context (UcContext) –

ctl(control, *args)

Parameters:

control (int) –

ctl_exits_enabled(val)

Parameters:

val (bool) –

ctl_flush_tb()

ctl_get_arch()

ctl_get_cpu_model()

ctl_get_exits()

ctl_get_exits_cnt()

ctl_get_mode()

ctl_get_page_size()

ctl_get_timeout()

ctl_remove_cache(addr, end)

Parameters:

• addr (int) –

• end (int) –

ctl_request_cache(addr)

Parameters:

addr (int) –

ctl_set_cpu_model(val)

Parameters:

val (int) –

ctl_set_exits(exits)

Parameters:

exits (List[int]) –

ctl_set_page_size(val)

Parameters:

val (int) –

emu_start(begin, until, timeout=0, count=0)

Return type:

None

Parameters:

• begin (int) –

• until (int) –

• timeout (int) –

• count (int) –

emu_stop()

Return type:

None

mem_protect(address, size, perms=7)

Parameters:

• address (int) –

• size (int) –

• perms (int) –

mem_read(address, size)

Parameters:

• address (int) –

• size (int) –

mem_regions()

mem_write(address, data)

Parameters:

• address (int) –

• data (bytes) –

mmio_map(address, size, read_cb, user_data_read, write_cb, user_data_write)

Parameters:

• address (int) –

• size (int) –

• read_cb (Callable[[Uc, int, int, Any], int]) –

• user_data_read (Any) –

• write_cb (Callable[[Uc, int, int, int, Any], None]) –

• user_data_write (Any) –

msr_read(msr_id)

Parameters:

msr_id (int) –

msr_write(msr_id, value)

Parameters:

value (int) –

query(query_mode)

Parameters:

query_mode (int) –

reg_read(reg_id, opt=None)

Return type:

Union[int, Tuple[int, int, int, int], Tuple[int, int]]

Parameters:

• reg_id (int) –

• opt (None | int | Tuple[int, int, int, int, int, int, int] | Tuple[int, int, int, int, int]) –

reg_write(reg_id, value)

Parameters:

• reg_id (int) –

• value (int | Tuple[int, int, int, int, int, int, int, int] | Tuple[int, int, int, int, int, int] | Tuple[int, int, int, int] | Tuple[int, int]) –

static release_handle(uch)

Parameters:

uch (CDLL) –

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_stop=2, cooldown_unsupported_stop=2, cooldown_nonunicorn_blocks=100, cooldown_stop_point=1, max_steps=1000000)

Bases: SimStatePlugin

setup the unicorn engine for a state

UC_CONFIG = {}

__init__(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_stop=2, cooldown_unsupported_stop=2, cooldown_nonunicorn_blocks=100, cooldown_stop_point=1, max_steps=1000000)

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

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

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

set_state(state)

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

property uc

static delete_uc()

set_last_block_details(details)

set_stops(stop_points)

set_tracking(track_bbls, track_stack)

hook()

uncache_region(addr, length)

clear_page_cache()

setup(syscall_data=None, fd_bytes=None)

start(step=None)

get_recent_bbl_addrs()

get_stop_details()

finish(succ_state)

destroy(succ_state)

set_regs()

setting unicorn registers

setup_flags()

setup_gdt(fs, gs)

read_msr(msr=3221225728)

write_msr(val, msr=3221225728)

get_regs(succ_state)

loading registers from unicorn. If succ_state is not None, update it instead of self.state. Needed when handling symbolic exits in native interface

STRONGREF_STATE = False

init_state()

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

static memo(f)

A decorator function you should apply to copy

classmethod register_default(name, xtr=None)

set_strongref_state(state)

state: angr.SimState

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

Bases: 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.

__init__(back_edge_trip_counts=None, header_trip_counts=None, current_loop=None)

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)

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

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

STRONGREF_STATE = False

init_state()

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

static memo(f)

A decorator function you should apply to copy

classmethod register_default(name, xtr=None)

set_state(state)

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

set_strongref_state(state)

state: angr.SimState

class angr.state_plugins.concrete.Concrete(segment_registers_initialized=False, segment_registers_callback_initialized=False, whitelist=None, fs_register_bp=None, already_sync_objects_addresses=None)

Bases: SimStatePlugin

__init__(segment_registers_initialized=False, segment_registers_callback_initialized=False, whitelist=None, fs_register_bp=None, already_sync_objects_addresses=None)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

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

set_state(state)

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

sync()

Handle the switch between the concrete execution and angr. This method takes care of: 1- Synchronize registers. 2- Set a concrete target to the memory backer so the memory reads are redirected in the concrete process memory. 3- If possible restore the SimProcedures with the real addresses inside the concrete process. 4- Set an inspect point to sync the segments register as soon as they are read during the symbolic execution. 5- Flush all the pages loaded until now.

Returns:

STRONGREF_STATE = False

init_state()

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

static memo(f)

A decorator function you should apply to copy

classmethod register_default(name, xtr=None)

set_strongref_state(state)

state: angr.SimState

class angr.state_plugins.javavm_classloader.SimJavaVmClassloader(initialized_classes=None)

Bases: SimStatePlugin

JavaVM Classloader is used as an interface for resolving and initializing Java classes.

__init__(initialized_classes=None)

get_class(class_name, init_class=False, step_func=None)

Get a class descriptor for the class.

Parameters:

• class_name (str) – Name of class.

• init_class (bool) – Whether the class initializer <clinit> should be executed.

• step_func (func) – Callback function executed at every step of the simulation manager during the execution of the main <clinit> method

get_superclass(class_)

Get the superclass of the class.

get_class_hierarchy(base_class)

Walks up the class hierarchy and returns a list of all classes between base class (inclusive) and java.lang.Object (exclusive).

is_class_initialized(class_)

Indicates whether the classes initializing method <clinit> was already executed on the state.

init_class(class_, step_func=None)

This method simulates the loading of a class by the JVM, during which parts of the class (e.g. static fields) are initialized. For this, we run the class initializer method <clinit> (if available) and update the state accordingly.

Note: Initialization is skipped, if the class has already been

initialized (or if it’s not loaded in CLE).

property initialized_classes

List of all initialized classes.

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

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

STRONGREF_STATE = False

init_state()

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

static memo(f)

A decorator function you should apply to copy

classmethod register_default(name, xtr=None)

set_state(state)

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

set_strongref_state(state)

state: angr.SimState

class angr.state_plugins.jni_references.SimStateJNIReferences(local_refs=None, global_refs=None)

Bases: SimStatePlugin

Management of the mapping between opaque JNI references and the corresponding Java objects.

__init__(local_refs=None, global_refs=None)

lookup(opaque_ref)

Lookups the object that was used for creating the reference.

create_new_reference(obj, global_ref=False)

Create a new reference thats maps to the given object.

Parameters:

• obj – Object which gets referenced.

• global_ref (bool) – Whether a local or global reference is created.

clear_local_references()

Clear all local references.

delete_reference(opaque_ref, global_ref=False)

Delete the stored mapping of a reference.

Parameters:

• opaque_ref – Reference which should be removed.

• global_ref (bool) – Whether opaque_ref is a local or global reference.

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

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

STRONGREF_STATE = False

init_state()

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

static memo(f)

A decorator function you should apply to copy

classmethod register_default(name, xtr=None)

set_state(state)

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

set_strongref_state(state)

state: angr.SimState

class angr.state_plugins.heap.heap_base.SimHeapBase(heap_base=None, heap_size=None)

Bases: SimStatePlugin

This is the base heap class that all heap implementations should subclass. It defines a few handlers for common heap functions (the libc memory management functions). Heap implementations are expected to override these functions regardless of whether they implement the SimHeapLibc interface. For an example, see the SimHeapBrk implementation, which is based on the original libc SimProcedure implementations.

Variables:

• heap_base – the address of the base of the heap in memory

• heap_size – the total size of the main memory region managed by the heap in memory

• mmap_base – the address of the region from which large mmap allocations will be made

__init__(heap_base=None, heap_size=None)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

init_state()

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

STRONGREF_STATE = False

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

classmethod register_default(name, xtr=None)

set_state(state)

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

set_strongref_state(state)

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

state: angr.SimState

class angr.state_plugins.heap.heap_brk.SimHeapBrk(heap_base=None, heap_size=None)

Bases: SimHeapBase

SimHeapBrk represents a trivial heap implementation based on the Unix brk system call. This type of heap stores virtually no metadata, so it is up to the user to determine when it is safe to release memory. This also means that it does not properly support standard heap operations like realloc.

This heap implementation is a holdover from before any more proper implementations were modelled. At the time, various libc (or win32) SimProcedures handled the heap in the same way that this plugin does now. To make future heap implementations plug-and-playable, they should implement the necessary logic themselves, and dependent SimProcedures should invoke a method by the same name as theirs (prepended with an underscore) upon the heap plugin. Depending on the heap implementation, if the method is not supported, an error should be raised.

Out of consideration for the original way the heap was handled, this plugin implements functionality for all relevant SimProcedures (even those that would not normally be supported together in a single heap implementation).

Variables:

heap_location – the address of the top of the heap, bounding the allocations made starting from heap_base

__init__(heap_base=None, heap_size=None)

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

allocate(sim_size)

The actual allocation primitive for this heap implementation. Increases the position of the break to allocate space. Has no guards against the heap growing too large.

Parameters:

sim_size – a size specifying how much to increase the break pointer by

Returns:

a pointer to the previous break position, above which there is now allocated space

release(sim_size)

The memory release primitive for this heap implementation. Decreases the position of the break to deallocate space. Guards against releasing beyond the initial heap base.

Parameters:

sim_size – a size specifying how much to decrease the break pointer by (may be symbolic or not)

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

STRONGREF_STATE = False

init_state()

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

static memo(f)

A decorator function you should apply to copy

classmethod register_default(name, xtr=None)

set_state(state)

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

set_strongref_state(state)

state: angr.SimState

class angr.state_plugins.heap.heap_freelist.Chunk(base, sim_state)

Bases: object

The sort of chunk as would typically be found in a freelist-style heap implementation. Provides a representation of a chunk via a view into the memory plugin. Chunks may be adjacent, in different senses, to as many as four other chunks. For any given chunk, two of these chunks are adjacent to it in memory, and are referred to as the “previous” and “next” chunks throughout this implementation. For any given free chunk, there may also be two significant chunks that are adjacent to it in some linked list of free chunks. These chunks are referred to the “backward” and “foward” chunks relative to the chunk in question.

Variables:

• base – the location of the base of the chunk in memory

• state – the program state that the chunk is resident in

__init__(base, sim_state)

get_size()

Returns the actual size of a chunk (as opposed to the entire size field, which may include some flags).

get_data_size()

Returns the size of the data portion of a chunk.

set_size(size)

Sets the size of the chunk, preserving any flags.

data_ptr()

Returns the address of the payload of the chunk.

is_free()

Returns a concrete determination as to whether the chunk is free.

next_chunk()

Returns the chunk immediately following (and adjacent to) this one.

prev_chunk()

Returns the chunk immediately prior (and adjacent) to this one.

fwd_chunk()

Returns the chunk following this chunk in the list of free chunks.

set_fwd_chunk(fwd)

Sets the chunk following this chunk in the list of free chunks.

Parameters:

fwd – the chunk to follow this chunk in the list of free chunks

bck_chunk()

Returns the chunk backward from this chunk in the list of free chunks.

set_bck_chunk(bck)

Sets the chunk backward from this chunk in the list of free chunks.

Parameters:

bck – the chunk to precede this chunk in the list of free chunks

class angr.state_plugins.heap.heap_freelist.SimHeapFreelist(heap_base=None, heap_size=None)

Bases: SimHeapLibc

A freelist-style heap implementation. Distinguishing features of such heaps include chunks containing heap metadata in addition to user data and at least (but often more than) one linked list of free chunks.

chunks()

Returns an iterator over all the chunks in the heap.

allocated_chunks()

Returns an iterator over all the allocated chunks in the heap.

free_chunks()

Returns an iterator over all the free chunks in the heap.

chunk_from_mem(ptr)

Given a pointer to a user payload, return the chunk associated with that payload.

Parameters:

ptr – a pointer to the base of a user payload in the heap

Returns:

the associated heap chunk

print_heap_state()

print_all_chunks()

STRONGREF_STATE = False

__init__(heap_base=None, heap_size=None)

calloc(sim_nmemb, sim_size)

A somewhat faithful implementation of libc calloc.

Parameters:

• sim_nmemb – the number of elements to allocated

• sim_size – the size of each element (in bytes)

Returns:

the address of the allocation, or a NULL pointer if the allocation failed

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

free(ptr)

A somewhat faithful implementation of libc free.

Parameters:

ptr – the location in memory to be freed

init_state()

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

malloc(sim_size)

A somewhat faithful implementation of libc malloc.

Parameters:

sim_size – the amount of memory (in bytes) to be allocated

Returns:

the address of the allocation, or a NULL pointer if the allocation failed

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

realloc(ptr, size)

A somewhat faithful implementation of libc realloc.

Parameters:

• ptr – the location in memory to be reallocated

• size – the new size desired for the allocation

Returns:

the address of the allocation, or a NULL pointer if the allocation was freed or if no new allocation was made

classmethod register_default(name, xtr=None)

set_state(state)

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

set_strongref_state(state)

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

state: angr.SimState

class angr.state_plugins.heap.heap_libc.SimHeapLibc(heap_base=None, heap_size=None)

Bases: SimHeapBase

A class of heap that implements the major libc heap management functions.

malloc(sim_size)

A somewhat faithful implementation of libc malloc.

Parameters:

sim_size – the amount of memory (in bytes) to be allocated

Returns:

the address of the allocation, or a NULL pointer if the allocation failed

free(ptr)

A somewhat faithful implementation of libc free.

Parameters:

ptr – the location in memory to be freed

calloc(sim_nmemb, sim_size)

A somewhat faithful implementation of libc calloc.

Parameters:

• sim_nmemb – the number of elements to allocated

• sim_size – the size of each element (in bytes)

Returns:

the address of the allocation, or a NULL pointer if the allocation failed

realloc(ptr, size)

A somewhat faithful implementation of libc realloc.

Parameters:

• ptr – the location in memory to be reallocated

• size – the new size desired for the allocation

Returns:

the address of the allocation, or a NULL pointer if the allocation was freed or if no new allocation was made

STRONGREF_STATE = False

__init__(heap_base=None, heap_size=None)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

init_state()

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

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

classmethod register_default(name, xtr=None)

set_state(state)

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

set_strongref_state(state)

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

state: angr.SimState

angr.state_plugins.heap.heap_ptmalloc.silence_logger()

angr.state_plugins.heap.heap_ptmalloc.unsilence_logger(level)

class angr.state_plugins.heap.heap_ptmalloc.PTChunk(base, sim_state, heap=None)

Bases: Chunk

A chunk, inspired by the implementation of chunks in ptmalloc. Provides a representation of a chunk via a view into the memory plugin. For the chunk definitions and docs that this was loosely based off of, see glibc malloc/malloc.c, line 1033, as of commit 5a580643111ef6081be7b4c7bd1997a5447c903f. Alternatively, take the following link. https://sourceware.org/git/?p=glibc.git;a=blob;f=malloc/malloc.c;h=67cdfd0ad2f003964cd0f7dfe3bcd85ca98528a7;hb=5a580643111ef6081be7b4c7bd1997a5447c903f#l1033

Variables:

• base – the location of the base of the chunk in memory

• state – the program state that the chunk is resident in

• heap – the heap plugin that the chunk is managed by

__init__(base, sim_state, heap=None)

get_size()

Returns the actual size of a chunk (as opposed to the entire size field, which may include some flags).

get_data_size()

Returns the size of the data portion of a chunk.

set_size(size, is_free=None)

Use this to set the size on a chunk. When the chunk is new (such as when a free chunk is shrunk to form an allocated chunk and a remainder free chunk) it is recommended that the is_free hint be used since setting the size depends on the chunk’s freeness, and vice versa.

Parameters:

• size – size of the chunk

• is_free – boolean indicating the chunk’s freeness

set_prev_freeness(is_free)

Sets (or unsets) the flag controlling whether the previous chunk is free.

Parameters:

is_free – if True, sets the previous chunk to be free; if False, sets it to be allocated

is_prev_free()

Returns a concrete state of the flag indicating whether the previous chunk is free or not. Issues a warning if that flag is symbolic and has multiple solutions, and then assumes that the previous chunk is free.

Returns:

True if the previous chunk is free; False otherwise

prev_size()

Returns the size of the previous chunk, masking off what would be the flag bits if it were in the actual size field. Performs NO CHECKING to determine whether the previous chunk size is valid (for example, when the previous chunk is not free, its size cannot be determined).

is_free()

Returns a concrete determination as to whether the chunk is free.

data_ptr()

Returns the address of the payload of the chunk.

next_chunk()

Returns the chunk immediately following (and adjacent to) this one, if it exists.

Returns:

The following chunk, or None if applicable

prev_chunk()

Returns the chunk immediately prior (and adjacent) to this one, if that chunk is free. If the prior chunk is not free, then its base cannot be located and this method raises an error.

Returns:

If possible, the previous chunk; otherwise, raises an error

fwd_chunk()

Returns the chunk following this chunk in the list of free chunks. If this chunk is not free, then it resides in no such list and this method raises an error.

Returns:

If possible, the forward chunk; otherwise, raises an error

set_fwd_chunk(fwd)

Sets the chunk following this chunk in the list of free chunks.

Parameters:

fwd – the chunk to follow this chunk in the list of free chunks

bck_chunk()

Returns the chunk backward from this chunk in the list of free chunks. If this chunk is not free, then it resides in no such list and this method raises an error.

Returns:

If possible, the backward chunk; otherwise, raises an error

set_bck_chunk(bck)

Sets the chunk backward from this chunk in the list of free chunks.

Parameters:

bck – the chunk to precede this chunk in the list of free chunks

class angr.state_plugins.heap.heap_ptmalloc.PTChunkIterator(chunk, cond=<function PTChunkIterator.<lambda>>)

Bases: object

__init__(chunk, cond=<function PTChunkIterator.<lambda>>)

class angr.state_plugins.heap.heap_ptmalloc.SimHeapPTMalloc(heap_base=None, heap_size=None)

Bases: SimHeapFreelist

A freelist-style heap implementation inspired by ptmalloc. The chunks used by this heap contain heap metadata in addition to user data. While the real-world ptmalloc is implemented using multiple lists of free chunks (corresponding to their different sizes), this more basic model uses a single list of chunks and searches for free chunks using a first-fit algorithm.

NOTE: The plugin must be registered using register_plugin with name heap in order to function properly.

Variables:

• heap_base – the address of the base of the heap in memory

• heap_size – the total size of the main memory region managed by the heap in memory

• mmap_base – the address of the region from which large mmap allocations will be made

• free_head_chunk – the head of the linked list of free chunks in the heap

__init__(heap_base=None, heap_size=None)

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

chunks()

Returns an iterator over all the chunks in the heap.

allocated_chunks()

Returns an iterator over all the allocated chunks in the heap.

free_chunks()

Returns an iterator over all the free chunks in the heap.

chunk_from_mem(ptr)

Given a pointer to a user payload, return the base of the chunk associated with that payload (i.e. the chunk pointer). Returns None if ptr is null.

Parameters:

ptr – a pointer to the base of a user payload in the heap

Returns:

a pointer to the base of the associated heap chunk, or None if ptr is null

malloc(sim_size)

A somewhat faithful implementation of libc malloc.

Parameters:

sim_size – the amount of memory (in bytes) to be allocated

Returns:

the address of the allocation, or a NULL pointer if the allocation failed

free(ptr)

A somewhat faithful implementation of libc free.

Parameters:

ptr – the location in memory to be freed

calloc(sim_nmemb, sim_size)

A somewhat faithful implementation of libc calloc.

Parameters:

• sim_nmemb – the number of elements to allocated

• sim_size – the size of each element (in bytes)

Returns:

the address of the allocation, or a NULL pointer if the allocation failed

realloc(ptr, size)

A somewhat faithful implementation of libc realloc.

Parameters:

• ptr – the location in memory to be reallocated

• size – the new size desired for the allocation

Returns:

the address of the allocation, or a NULL pointer if the allocation was freed or if no new allocation was made

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

init_state()

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

STRONGREF_STATE = False

static memo(f)

A decorator function you should apply to copy

print_all_chunks()

print_heap_state()

classmethod register_default(name, xtr=None)

set_state(state)

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

set_strongref_state(state)

state: angr.SimState

angr.state_plugins.heap.utils.concretize(x, solver, sym_handler)

For now a lot of naive concretization is done when handling heap metadata to keep things manageable. This idiom showed up a lot as a result, so to reduce code repetition this function uses a callback to handle the one or two operations that varied across invocations.

Parameters:

• x – the item to be concretized

• solver – the solver to evaluate the item with

• sym_handler – the handler to be used when the item may take on more than one value

Returns:

a concrete value for the item

class angr.state_plugins.symbolizer.SimSymbolizer

Bases: SimStatePlugin

The symbolizer state plugin ensures that pointers that are stored in memory are symbolic. This allows for the tracking of and reasoning over these pointers (for example, to reason about memory disclosure).

__init__()

init_state()

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

set_symbolization_for_all_pages()

Sets the symbolizer to symbolize pointers to all pages as they are written to memory..

set_symbolized_target_range(base, length)

All pointers to the target range will be symbolized as they are written to memory.

Due to optimizations, the _pages_ containing this range will be set as symbolization targets, not just the range itself.

resymbolize()

Re-symbolizes all pointers in memory. This can be called to symbolize any pointers to target regions that were written (and not mangled beyond recognition) before symbolization was set.

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

STRONGREF_STATE = False

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

classmethod register_default(name, xtr=None)

set_state(state)

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

set_strongref_state(state)

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

state: angr.SimState

class angr.state_plugins.debug_variables.SimDebugVariable(state, addr, var_type)

Bases: object

A SimDebugVariable will get dynamically created when queriyng for variable in a state with the SimDebugVariablePlugin. It features a link to the state, an address and a type.

Parameters:

• state (SimState) –

• var_type (VariableType) –

__init__(state, addr, var_type)

Parameters:

• state (SimState) –

• var_type (VariableType) –

static from_cle_variable(state, cle_variable, dwarf_cfa)

Return type:

SimDebugVariable

Parameters:

• state (SimState) –

• cle_variable (Variable) –

property mem_untyped: SimMemView

property mem: SimMemView

property string: SimMemView

with_type(sim_type)

Return type:

SimMemView

Parameters:

sim_type (SimType) –

property resolvable

property resolved

property concrete

store(value)

property deref: SimDebugVariable

array(i)

Return type:

SimDebugVariable

member(member_name)

Return type:

SimDebugVariable

Parameters:

member_name (str) –

class angr.state_plugins.debug_variables.SimDebugVariablePlugin

Bases: SimStatePlugin

This is the plugin you’ll use to interact with (global/local) program variables. These variables have a name and a visibility scope which depends on the pc address of the state. With this plugin, you can access/modify the value of such variable or find its memory address. For creating program varibles, or for importing them from cle, see the knowledge plugin debug_variables. Run p.kb.dvars.load_from_dwarf() before using this plugin.

Example

>>> p = angr.Project("various_variables", load_debug_info=True)
>>> p.kb.dvars.load_from_dwarf()
>>> state =  # navigate to the state you want
>>> state.dvars.get_variable("pointer2").deref.mem
<int (32 bits) <BV32 0x1> at 0x404020>

get_variable(var_name)

Returns the visible variable (if any) with name var_name based on the current state.ip.

Return type:

SimDebugVariable

Parameters:

var_name (str) –

property dwarf_cfa

Returns the current cfa computation. Set this property to the correct value if needed.

STRONGREF_STATE = False

__init__()

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

property dwarf_cfa_approx

init_state()

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

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

classmethod register_default(name, xtr=None)

set_state(state)

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

set_strongref_state(state)

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

state: angr.SimState

Storage

class angr.state_plugins.view.SimRegNameView

Bases: SimStatePlugin

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

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

get(reg_name)

STRONGREF_STATE = False

__init__()

init_state()

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

static memo(f)

A decorator function you should apply to copy

classmethod register_default(name, xtr=None)

set_state(state)

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

set_strongref_state(state)

state: angr.SimState

class angr.state_plugins.view.SimMemView(ty=None, addr=None, state=None)

Bases: 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'

Parameters:

state (SimState) –

__init__(ty=None, addr=None, state=None)

set_state(state)

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

types = {'CharT': char, 'FILE_t': struct FILE_t, '_Bool': bool, '_ENTRY': struct _ENTRY, '_IO_codecvt': struct _IO_codecvt, '_IO_iconv_t': struct _IO_iconv_t, '_IO_lock_t': struct pthread_mutex_t, '_IO_marker': struct _IO_marker, '_IO_wide_data': struct _IO_wide_data, '__clock_t': uint32_t, '__dev_t': uint64_t, '__gid_t': unsigned int, '__ino64_t': unsigned long long, '__ino_t': unsigned long, '__int128': int128_t, '__int256': int256_t, '__mbstate_t': struct __mbstate_t, '__mode_t': unsigned int, '__nlink_t': unsigned int, '__off64_t': long long, '__off_t': long, '__pid_t': int, '__suseconds_t': int64_t, '__time_t': long, '__uid_t': unsigned int, '_obstack_chunk': struct _obstack_chunk, 'aiocb': struct aiocb, 'aiocb64': struct aiocb64, 'aioinit': struct aioinit, 'argp': struct argp, 'argp_child': struct argp_child, 'argp_option': struct argp_option, 'argp_parser_t': (int, char*, struct argp_state*) -> int, 'argp_state': struct argp_state, 'basic_string': string_t, 'bool': bool, 'byte': uint8_t, 'cc_t': char, 'char': char, 'clock_t': uint32_t, 'crypt_data': struct crypt_data, 'dirent': struct dirent, 'dirent64': struct dirent64, 'double': double, 'drand48_data': struct <anon>, 'dword': uint32_t, 'error_t': int, 'exit_status': struct exit_status, 'float': float, 'fstab': struct fstab, 'group': struct group, 'hostent': struct hostent, 'hsearch_data': struct hsearch_data, 'if_nameindex': struct if_nameindex, 'in_addr': struct in_addr, 'in_port_t': uint16_t, 'ino64_t': unsigned long long, 'ino_t': unsigned long, 'int': int, 'int16_t': int16_t, 'int32_t': int32_t, 'int64_t': int64_t, 'int8_t': int8_t, 'iovec': struct <anon>, 'itimerval': struct itimerval, 'lconv': struct lconv, 'long': long, 'long double': double, 'long int': long, 'long long': long long, 'long long int': long long, 'long signed': long, 'long unsigned int': unsigned long, 'mallinfo': struct mallinfo, 'mallinfo2': struct mallinfo2, 'mntent': struct mntent, 'netent': struct netent, 'ntptimeval': struct ntptimeval, 'obstack': struct obstack, 'off64_t': long long, 'off_t': long, 'option': struct option, 'passwd': struct passwd, 'pid_t': int, 'printf_info': struct printf_info, 'protoent': struct protoent, 'ptrdiff_t': long, 'qword': uint64_t, 'random_data': struct <anon>, 'rlim64_t': uint64_t, 'rlim_t': unsigned long, 'rlimit': struct rlimit, 'rlimit64': struct rlimit64, 'rusage': struct rusage, 'sa_family_t': unsigned short, 'sched_param': struct sched_param, 'sembuf': struct sembuf, 'servent': struct servent, 'sgttyb': struct sgttyb, 'short': short, 'short int': short, 'sigevent': struct sigevent, 'signed': int, '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, 'sigstack': struct sigstack, 'sigval': union sigval { sival_int int; sival_ptr void*; }, 'size_t': size_t, 'sockaddr': struct sockaddr, 'sockaddr_in': struct sockaddr_in, 'speed_t': long, 'ssize': size_t, 'ssize_t': size_t, 'stat': struct stat, 'stat64': struct stat64, 'string': string_t, 'struct iovec': struct iovec, 'struct timespec': struct timespec, 'struct timeval': struct timeval, 'tcflag_t': unsigned long, 'termios': struct termios, 'time_t': long, 'timespec': struct timeval, 'timeval': struct timeval, 'timex': struct timex, 'timezone': struct timezone, 'tm': struct tm, 'tms': struct tms, 'uint16_t': uint16_t, 'uint32_t': uint32_t, 'uint64_t': uint64_t, 'uint8_t': uint8_t, 'uintptr_t': unsigned long, 'unsigned': unsigned int, 'unsigned __int128': uint128_t, 'unsigned __int256': uint256_t, '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, 'utimbuf': struct utimbuf, 'utmp': struct utmp, 'utmpx': struct utmx, 'utsname': struct utsname, 'va_list': struct va_list[1], 'void': void, 'vtimes': struct vtimes, 'wchar_t': short, 'winsize': struct winsize, 'word': uint16_t, 'wstring': wstring_t}

state: angr.SimState = None

struct: StructMode

with_type(sim_type)

Returns a copy of the SimMemView with a type.

Parameters:

sim_type (SimType) – The new type.

Return type:

SimMemView

Returns:

The typed SimMemView copy.

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

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

property resolvable

property resolved

property concrete

property deref: SimMemView

array(n)

Return type:

SimMemView

member(member_name)

If self is a struct and member_name is a member of the struct, return that member element. Otherwise raise an exception.

Return type:

SimMemView

Parameters:

member_name (str) –

store(value)

STRONGREF_STATE = False

init_state()

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

static memo(f)

A decorator function you should apply to copy

classmethod register_default(name, xtr=None)

set_strongref_state(state)

class angr.state_plugins.view.StructMode(view)

Bases: object

__init__(view)

class angr.storage.file.Flags

Bases: object

O_RDONLY = 0

O_WRONLY = 1

O_RDWR = 2

O_ACCMODE = 3

O_APPEND = 1024

O_ASYNC = 8192

O_CLOEXEC = 524288

O_CREAT = 64

O_DIRECT = 16384

O_DIRECTORY = 65536

O_DSYNC = 4096

O_EXCL = 128

O_LARGEFILE = 32768

O_NOATIME = 262144

O_NOCTTY = 256

O_NOFOLLOW = 131072

O_NONBLOCK = 2048

O_NDELAY = 2048

O_PATH = 2097152

O_SYNC = 1052672

O_TMPFILE = 4259840

O_TRUNC = 512

class angr.storage.file.SimFileBase(name=None, writable=True, ident=None, concrete=False, file_exists=True, **kwargs)

Bases: 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.

• file_exists – Set to False, if file does not exists, set to a claripy Bool if unknown, default True.

seekable = False

pos = None

__init__(name=None, writable=True, ident=None, concrete=False, file_exists=True, **kwargs)

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.

property size

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

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

STRONGREF_STATE = False

init_state()

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

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

classmethod register_default(name, xtr=None)

set_state(state)

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

set_strongref_state(state)

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

state: angr.SimState

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

Bases: SimFileBase, DefaultMemory

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

__init__(name=None, content=None, size=None, has_end=None, seekable=True, writable=True, ident=None, concrete=None, **kwargs)

seekable = False

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

set_state(state)

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

property size

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

concretize(**kwargs)

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

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, events=True, **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.

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

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

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

PAGE_TYPE

alias of UltraPage

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = True

addrs_for_hash(h)

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

addrs_for_name(n)

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

allocate_stack_pages(addr, size, **kwargs)

Pre-allocates pages for the stack without triggering any logic related to reading from them.

Parameters:

• addr (int) – The highest address that should be mapped

• size (int) – The number of bytes to be allocated. byte 1 is the one at addr, byte 2 is the one before that, and so on.

Returns:

A list of the new page objects

changed_bytes(other)

Return type:

Set[int]

changed_pages(other)

Return type:

Dict[int, Optional[Set[int]]]

concrete_load(addr, size, *args, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Returns:

A memoryview into the loaded bytes.

concretize_read_addr(addr, strategies=None, condition=None)

Concretizes an address meant for reading.

Parameters:

• addr – An expression for the address.

• strategies – A list of concretization strategies (to override the default).

Returns:

A list of concrete addresses.

concretize_write_addr(addr, strategies=None, condition=None)

Concretizes an address meant for writing.

Parameters:

• addr – An expression for the address.

• strategies – A list of concretization strategies (to override the default).

• condition – Any extra constraints that should be observed when determining address satisfiability

Returns:

A list of concrete addresses.

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, needle, max_search, default=None, endness=None, chunk_size=None, max_symbolic_bytes=None, condition=None, char_size=1, **kwargs)

flush_pages(white_list)

Flush all pages not included in the white_list by removing their pages. Note, this will not wipe them from memory if they were backed by a memory_backer, it will simply reset them to their initial state. Returns the list of pages that were cleared consisting of (addr, length) tuples. :type white_list: :param white_list: white list of regions in the form of (start, end) to exclude from the flush :return: a list of memory page ranges that were flushed :rtype: list

get_symbolic_addrs()

hex_dump(start, size, word_size=4, words_per_row=4, endianness='Iend_BE', symbolic_char='?', unprintable_char='.', solve=False, extra_constraints=None, inspect=False, disable_actions=True)

Returns a hex dump as a string. The solver, if enabled, is called once for every byte potentially making this function very slow. It is meant to be used mainly as a “visualization” for debugging.

Warning: May read and display more bytes than size due to rounding. Particularly, if size is less than, or not a multiple of word_size*words_per_line.

Parameters:

• start – starting address from which to print

• size – number of bytes to display

• word_size – number of bytes to group together as one space-delimited unit

• words_per_row – number of words to display per row of output

• endianness – endianness to use when displaying each word (ASCII representation is unchanged)

• symbolic_char – the character to display when a byte is symbolic and has multiple solutions

• unprintable_char – the character to display when a byte is not printable

• solve – whether or not to attempt to solve (warning: can be very slow)

• extra_constraints – extra constraints to pass to the solver is solve is True

• inspect – whether or not to trigger SimInspect breakpoints for the memory load

• disable_actions – whether or not to disable SimActions for the memory load

Returns:

hex dump as a string

init_state()

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

load(addr, size=None, condition=None, fallback=None, **kwargs)

static make_ident(name)

map_region(addr, length, permissions, **kwargs)

static memo(f)

A decorator function you should apply to copy

permissions(addr, permissions=None, **kwargs)

pos = None

classmethod register_default(name, xtr=None)

replace_all(old, new)

Replaces all instances of expression old with expression new.

Parameters:

• old (BV) – A claripy expression. Must contain at least one named variable (to make it possible to use the name index for speedup).

• new (BV) – The new variable to replace it with.

set_strongref_state(state)

store(addr, data, size=None, condition=None, **kwargs)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

state: angr.SimState

class angr.storage.file.SimFileStream(name=None, content=None, pos=0, **kwargs)

Bases: 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.

__init__(name=None, content=None, pos=0, **kwargs)

pos = None

set_state(state)

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

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(_, 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.

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

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

PAGE_TYPE

alias of UltraPage

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = True

addrs_for_hash(h)

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

addrs_for_name(n)

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

allocate_stack_pages(addr, size, **kwargs)

Pre-allocates pages for the stack without triggering any logic related to reading from them.

Parameters:

• addr (int) – The highest address that should be mapped

• size (int) – The number of bytes to be allocated. byte 1 is the one at addr, byte 2 is the one before that, and so on.

Returns:

A list of the new page objects

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

changed_bytes(other)

Return type:

Set[int]

changed_pages(other)

Return type:

Dict[int, Optional[Set[int]]]

concrete_load(addr, size, *args, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Returns:

A memoryview into the loaded bytes.

concretize(**kwargs)

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

concretize_read_addr(addr, strategies=None, condition=None)

Concretizes an address meant for reading.

Parameters:

• addr – An expression for the address.

• strategies – A list of concretization strategies (to override the default).

Returns:

A list of concrete addresses.

concretize_write_addr(addr, strategies=None, condition=None)

Concretizes an address meant for writing.

Parameters:

• addr – An expression for the address.

• strategies – A list of concretization strategies (to override the default).

• condition – Any extra constraints that should be observed when determining address satisfiability

Returns:

A list of concrete addresses.

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, needle, max_search, default=None, endness=None, chunk_size=None, max_symbolic_bytes=None, condition=None, char_size=1, **kwargs)

flush_pages(white_list)

Flush all pages not included in the white_list by removing their pages. Note, this will not wipe them from memory if they were backed by a memory_backer, it will simply reset them to their initial state. Returns the list of pages that were cleared consisting of (addr, length) tuples. :type white_list: :param white_list: white list of regions in the form of (start, end) to exclude from the flush :return: a list of memory page ranges that were flushed :rtype: list

get_symbolic_addrs()

hex_dump(start, size, word_size=4, words_per_row=4, endianness='Iend_BE', symbolic_char='?', unprintable_char='.', solve=False, extra_constraints=None, inspect=False, disable_actions=True)

Returns a hex dump as a string. The solver, if enabled, is called once for every byte potentially making this function very slow. It is meant to be used mainly as a “visualization” for debugging.

Warning: May read and display more bytes than size due to rounding. Particularly, if size is less than, or not a multiple of word_size*words_per_line.

Parameters:

• start – starting address from which to print

• size – number of bytes to display

• word_size – number of bytes to group together as one space-delimited unit

• words_per_row – number of words to display per row of output

• endianness – endianness to use when displaying each word (ASCII representation is unchanged)

• symbolic_char – the character to display when a byte is symbolic and has multiple solutions

• unprintable_char – the character to display when a byte is not printable

• solve – whether or not to attempt to solve (warning: can be very slow)

• extra_constraints – extra constraints to pass to the solver is solve is True

• inspect – whether or not to trigger SimInspect breakpoints for the memory load

• disable_actions – whether or not to disable SimActions for the memory load

Returns:

hex dump as a string

init_state()

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

load(addr, size=None, condition=None, fallback=None, **kwargs)

static make_ident(name)

map_region(addr, length, permissions, **kwargs)

static memo(f)

A decorator function you should apply to copy

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Replaces all instances of expression old with expression new.

Parameters:

• old (BV) – A claripy expression. Must contain at least one named variable (to make it possible to use the name index for speedup).

• new (BV) – The new variable to replace it with.

seekable = False

set_strongref_state(state)

property size

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

store(addr, data, size=None, condition=None, **kwargs)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

widen(_)

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

state: angr.SimState

class angr.storage.file.SimPackets(name, write_mode=None, content=None, writable=True, ident=None, **kwargs)

Bases: 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.

__init__(name, write_mode=None, content=None, writable=True, ident=None, **kwargs)

set_state(state)

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

property size

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

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)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

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

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

STRONGREF_STATE = False

init_state()

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

static make_ident(name)

static memo(f)

A decorator function you should apply to copy

pos = None

classmethod register_default(name, xtr=None)

seekable = False

set_strongref_state(state)

state: angr.SimState

class angr.storage.file.SimPacketsStream(name, pos=0, **kwargs)

Bases: 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.

__init__(name, pos=0, **kwargs)

pos = None

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(_, data, size=None, **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)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

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

STRONGREF_STATE = False

concretize(**kwargs)

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

init_state()

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

static make_ident(name)

static memo(f)

A decorator function you should apply to copy

classmethod register_default(name, xtr=None)

seekable = False

set_state(state)

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

set_strongref_state(state)

property size

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

widen(_)

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

state: angr.SimState

class angr.storage.file.SimFileDescriptorBase

Bases: 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.

property read_storage

Return the SimFile backing reads from this fd

property write_storage

Return the SimFile backing writes to this fd

property 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.

property 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 different data structures on a per-class basis.

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

property file_exists

This should be True in most cases. Only if we opened an fd of unknown existence, ALL_FILES_EXIST is False and ANY_FILE_MIGHT_EXIST is True, this is a symbolic boolean.

STRONGREF_STATE = False

__init__()

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

init_state()

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

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

classmethod register_default(name, xtr=None)

set_state(state)

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

set_strongref_state(state)

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

state: angr.SimState

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

Bases: 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

__init__(simfile, flags=0)

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

eof()

Return the EOF status. May be a symbolic boolean.

tell()

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

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.

concretize(**kwargs)

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

property file_exists

This should be True in most cases. Only if we opened an fd of unknown existence, ALL_FILES_EXIST is False and ANY_FILE_MIGHT_EXIST is True, this is a symbolic boolean.

property read_storage

Return the SimFile backing reads from this fd

property write_storage

Return the SimFile backing writes to this fd

property 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.

property 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.

set_state(state)

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

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

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

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

STRONGREF_STATE = False

init_state()

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

static memo(f)

A decorator function you should apply to copy

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

classmethod register_default(name, xtr=None)

set_strongref_state(state)

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

state: angr.SimState

class angr.storage.file.SimFileDescriptorDuplex(read_file, write_file)

Bases: 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

__init__(read_file, write_file)

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

set_state(state)

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

eof()

Return the EOF status. May be a symbolic boolean.

tell()

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

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

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.

concretize(**kwargs)

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

property read_storage

Return the SimFile backing reads from this fd

property write_storage

Return the SimFile backing writes to this fd

property 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.

property 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.

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

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

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

STRONGREF_STATE = False

property file_exists

This should be True in most cases. Only if we opened an fd of unknown existence, ALL_FILES_EXIST is False and ANY_FILE_MIGHT_EXIST is True, this is a symbolic boolean.

init_state()

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

static memo(f)

A decorator function you should apply to copy

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

classmethod register_default(name, xtr=None)

set_strongref_state(state)

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

state: angr.SimState

class angr.storage.file.SimPacketsSlots(name, read_sizes, ident=None, **kwargs)

Bases: 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

__init__(name, read_sizes, ident=None, **kwargs)

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.

property size

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

STRONGREF_STATE = False

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

init_state()

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

static make_ident(name)

static memo(f)

A decorator function you should apply to copy

pos = None

classmethod register_default(name, xtr=None)

set_state(state)

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

set_strongref_state(state)

state: angr.SimState

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

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

angr.storage.memory_object.obj_bit_size(o)

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

Bases: object

A SimMemoryObject is a reference to a byte or several bytes in a specific object in memory. It should be used only by the bottom layer of memory.

__init__(obj, base, endness, length=None, byte_width=8)

is_bytes

base

object

length

endness

size()

property variables

property cache_key

property symbolic

property last_addr

includes(x)

bytes_at(addr, length, allow_concrete=False, endness='Iend_BE')

class angr.storage.memory_object.SimLabeledMemoryObject(obj, base, endness, length=None, byte_width=8, label=None)

Bases: SimMemoryObject

__init__(obj, base, endness, length=None, byte_width=8, label=None)

label

base

bytes_at(addr, length, allow_concrete=False, endness='Iend_BE')

property cache_key

endness

includes(x)

is_bytes

property last_addr

length

object

size()

property symbolic

property variables

angr.storage.memory_object.bv_slice(value, offset, size, rev, bw)

Extremely cute utility to pretend you’ve serialized a value to stored bytes, sliced it a la python slicing, and then deserialized those bytes to an integer again.

Parameters:

• value – The bitvector to slice

• offset – The byte offset from the first stored byte to slice from, or a negative offset from the end.

• size – The number of bytes to return. If None, return all bytes from the offset to the end. If larger than the number of bytes from the offset to the end, return all bytes from the offset to the end.

• rev – Whether the pretend-serialization should be little-endian

• bw – The byte width

Returns:

The new bitvector

class angr.storage.pcap.PCAP(path, ip_port_tup, init=True)

Bases: object

__init__(path, ip_port_tup, init=True)

initialize(path)

recv(length)

copy()

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.

__init__(filter=None, exact=True)

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, **kwargs)

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.

Memory Mixins

class angr.storage.memory_mixins.MemoryMixin(memory_id=None, endness='Iend_BE')

Bases: SimStatePlugin

SUPPORTS_CONCRETE_LOAD = False

__init__(memory_id=None, endness='Iend_BE')

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

property variable_key_prefix

find(addr, data, max_search, **kwargs)

load(addr, **kwargs)

store(addr, data, **kwargs)

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

permissions(addr, permissions=None, **kwargs)

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

unmap_region(addr, length, **kwargs)

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

STRONGREF_STATE = False

init_state()

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

static memo(f)

A decorator function you should apply to copy

classmethod register_default(name, xtr=None)

set_state(state)

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

set_strongref_state(state)

state: angr.SimState

class angr.storage.memory_mixins.DefaultMemory(*args, **kwargs)

Bases: HexDumperMixin, SmartFindMixin, UnwrapperMixin, NameResolutionMixin, DataNormalizationMixin, SimplificationMixin, InspectMixinHigh, ActionsMixinHigh, UnderconstrainedMixin, SizeConcretizationMixin, SizeNormalizationMixin, AddressConcretizationMixin, ActionsMixinLow, ConditionalMixin, ConvenientMappingsMixin, DirtyAddrsMixin, StackAllocationMixin, ConcreteBackerMixin, ClemoryBackerMixin, DictBackerMixin, PrivilegedPagingMixin, UltraPagesMixin, DefaultFillerMixin, SymbolicMergerMixin, PagedMemoryMixin

PAGE_TYPE

alias of UltraPage

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = True

__init__(*args, **kwargs)

addrs_for_hash(h)

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

addrs_for_name(n)

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

allocate_stack_pages(addr, size, **kwargs)

Pre-allocates pages for the stack without triggering any logic related to reading from them.

Parameters:

• addr (int) – The highest address that should be mapped

• size (int) – The number of bytes to be allocated. byte 1 is the one at addr, byte 2 is the one before that, and so on.

Returns:

A list of the new page objects

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

changed_bytes(other)

Return type:

Set[int]

changed_pages(other)

Return type:

Dict[int, Optional[Set[int]]]

concrete_load(addr, size, *args, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Returns:

A memoryview into the loaded bytes.

concretize_read_addr(addr, strategies=None, condition=None)

Concretizes an address meant for reading.

Parameters:

• addr – An expression for the address.

• strategies – A list of concretization strategies (to override the default).

Returns:

A list of concrete addresses.

concretize_write_addr(addr, strategies=None, condition=None)

Concretizes an address meant for writing.

Parameters:

• addr – An expression for the address.

• strategies – A list of concretization strategies (to override the default).

• condition – Any extra constraints that should be observed when determining address satisfiability

Returns:

A list of concrete addresses.

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, needle, max_search, default=None, endness=None, chunk_size=None, max_symbolic_bytes=None, condition=None, char_size=1, **kwargs)

flush_pages(white_list)

Flush all pages not included in the white_list by removing their pages. Note, this will not wipe them from memory if they were backed by a memory_backer, it will simply reset them to their initial state. Returns the list of pages that were cleared consisting of (addr, length) tuples. :type white_list: :param white_list: white list of regions in the form of (start, end) to exclude from the flush :return: a list of memory page ranges that were flushed :rtype: list

get_symbolic_addrs()

hex_dump(start, size, word_size=4, words_per_row=4, endianness='Iend_BE', symbolic_char='?', unprintable_char='.', solve=False, extra_constraints=None, inspect=False, disable_actions=True)

Returns a hex dump as a string. The solver, if enabled, is called once for every byte potentially making this function very slow. It is meant to be used mainly as a “visualization” for debugging.

Warning: May read and display more bytes than size due to rounding. Particularly, if size is less than, or not a multiple of word_size*words_per_line.

Parameters:

• start – starting address from which to print

• size – number of bytes to display

• word_size – number of bytes to group together as one space-delimited unit

• words_per_row – number of words to display per row of output

• endianness – endianness to use when displaying each word (ASCII representation is unchanged)

• symbolic_char – the character to display when a byte is symbolic and has multiple solutions

• unprintable_char – the character to display when a byte is not printable

• solve – whether or not to attempt to solve (warning: can be very slow)

• extra_constraints – extra constraints to pass to the solver is solve is True

• inspect – whether or not to trigger SimInspect breakpoints for the memory load

• disable_actions – whether or not to disable SimActions for the memory load

Returns:

hex dump as a string

init_state()

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

load(addr, size=None, condition=None, fallback=None, **kwargs)

map_region(addr, length, permissions, **kwargs)

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Replaces all instances of expression old with expression new.

Parameters:

• old (BV) – A claripy expression. Must contain at least one named variable (to make it possible to use the name index for speedup).

• new (BV) – The new variable to replace it with.

set_state(state)

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

set_strongref_state(state)

store(addr, data, size=None, condition=None, **kwargs)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.DefaultListPagesMemory(*args, **kwargs)

Bases: HexDumperMixin, SmartFindMixin, UnwrapperMixin, NameResolutionMixin, DataNormalizationMixin, SimplificationMixin, ActionsMixinHigh, UnderconstrainedMixin, SizeConcretizationMixin, SizeNormalizationMixin, InspectMixinHigh, AddressConcretizationMixin, ActionsMixinLow, ConditionalMixin, ConvenientMappingsMixin, DirtyAddrsMixin, StackAllocationMixin, ClemoryBackerMixin, DictBackerMixin, PrivilegedPagingMixin, ListPagesMixin, DefaultFillerMixin, SymbolicMergerMixin, PagedMemoryMixin

PAGE_TYPE

alias of ListPage

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = True

__init__(*args, **kwargs)

addrs_for_hash(h)

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

addrs_for_name(n)

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

allocate_stack_pages(addr, size, **kwargs)

Pre-allocates pages for the stack without triggering any logic related to reading from them.

Parameters:

• addr (int) – The highest address that should be mapped

• size (int) – The number of bytes to be allocated. byte 1 is the one at addr, byte 2 is the one before that, and so on.

Returns:

A list of the new page objects

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

changed_bytes(other)

Return type:

Set[int]

changed_pages(other)

Return type:

Dict[int, Optional[Set[int]]]

concrete_load(addr, size, *args, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Returns:

A memoryview into the loaded bytes.

concretize_read_addr(addr, strategies=None, condition=None)

Concretizes an address meant for reading.

Parameters:

• addr – An expression for the address.

• strategies – A list of concretization strategies (to override the default).

Returns:

A list of concrete addresses.

concretize_write_addr(addr, strategies=None, condition=None)

Concretizes an address meant for writing.

Parameters:

• addr – An expression for the address.

• strategies – A list of concretization strategies (to override the default).

• condition – Any extra constraints that should be observed when determining address satisfiability

Returns:

A list of concrete addresses.

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, needle, max_search, default=None, endness=None, chunk_size=None, max_symbolic_bytes=None, condition=None, char_size=1, **kwargs)

flush_pages(white_list)

Flush all pages not included in the white_list by removing their pages. Note, this will not wipe them from memory if they were backed by a memory_backer, it will simply reset them to their initial state. Returns the list of pages that were cleared consisting of (addr, length) tuples. :type white_list: :param white_list: white list of regions in the form of (start, end) to exclude from the flush :return: a list of memory page ranges that were flushed :rtype: list

get_symbolic_addrs()

hex_dump(start, size, word_size=4, words_per_row=4, endianness='Iend_BE', symbolic_char='?', unprintable_char='.', solve=False, extra_constraints=None, inspect=False, disable_actions=True)

Returns a hex dump as a string. The solver, if enabled, is called once for every byte potentially making this function very slow. It is meant to be used mainly as a “visualization” for debugging.

Warning: May read and display more bytes than size due to rounding. Particularly, if size is less than, or not a multiple of word_size*words_per_line.

Parameters:

• start – starting address from which to print

• size – number of bytes to display

• word_size – number of bytes to group together as one space-delimited unit

• words_per_row – number of words to display per row of output

• endianness – endianness to use when displaying each word (ASCII representation is unchanged)

• symbolic_char – the character to display when a byte is symbolic and has multiple solutions

• unprintable_char – the character to display when a byte is not printable

• solve – whether or not to attempt to solve (warning: can be very slow)

• extra_constraints – extra constraints to pass to the solver is solve is True

• inspect – whether or not to trigger SimInspect breakpoints for the memory load

• disable_actions – whether or not to disable SimActions for the memory load

Returns:

hex dump as a string

init_state()

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

load(addr, size=None, condition=None, fallback=None, **kwargs)

map_region(addr, length, permissions, **kwargs)

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Replaces all instances of expression old with expression new.

Parameters:

• old (BV) – A claripy expression. Must contain at least one named variable (to make it possible to use the name index for speedup).

• new (BV) – The new variable to replace it with.

set_state(state)

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

set_strongref_state(state)

store(addr, data, size=None, condition=None, **kwargs)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.FastMemory(uninitialized_read_handler=None, **kwargs)

Bases: NameResolutionMixin, SimpleInterfaceMixin, SimplificationMixin, InspectMixinHigh, ConditionalMixin, ExplicitFillerMixin, DefaultFillerMixin, SlottedMemoryMixin

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

__init__(uninitialized_read_handler=None, **kwargs)

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

changed_bytes(other)

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

load(addr, size=None, **kwargs)

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

store(addr, data, size=None, **kwargs)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.AbstractMemory(*args, **kwargs)

Bases: UnwrapperMixin, NameResolutionMixin, DataNormalizationMixin, SimplificationMixin, InspectMixinHigh, ActionsMixinHigh, UnderconstrainedMixin, SizeConcretizationMixin, SizeNormalizationMixin, ActionsMixinLow, ConditionalMixin, RegionedAddressConcretizationMixin, RegionedMemoryMixin

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

__init__(*args, **kwargs)

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, what, max_search, default=None, **kwargs)

init_state()

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

load(addr, size=None, condition=None, fallback=None, **kwargs)

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

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 (int) – The absolute memory address.

• region_id (str) – The region ID.

• related_function_address (Optional[int]) – Related function address.

set_stack_size(size)

Parameters:

size (int) –

set_state(state)

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

set_strongref_state(state)

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.

Return type:

str

Returns:

ID of the new memory region.

store(addr, data, size=None, condition=None, **kwargs)

unmap_region(addr, length, **kwargs)

unset_stack_address_mapping(absolute_address)

Remove a stack mapping.

Parameters:

absolute_address (int) – An absolute memory address that is the base address of the stack frame to destroy.

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.RegionedMemory(related_function_addr=None, **kwargs)

Bases: RegionCategoryMixin, MemoryRegionMetaMixin, StaticFindMixin, UnwrapperMixin, NameResolutionMixin, DataNormalizationMixin, SimplificationMixin, SizeConcretizationMixin, SizeNormalizationMixin, AddressConcretizationMixin, ConvenientMappingsMixin, DirtyAddrsMixin, ClemoryBackerMixin, DictBackerMixin, UltraPagesMixin, DefaultFillerMixin, AbstractMergerMixin, PagedMemoryMixin

PAGE_TYPE

alias of UltraPage

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = True

__init__(related_function_addr=None, **kwargs)

addrs_for_hash(h)

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

addrs_for_name(n)

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

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

changed_bytes(other)

Return type:

Set[int]

changed_pages(other)

Return type:

Dict[int, Optional[Set[int]]]

concrete_load(addr, size, *args, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Returns:

A memoryview into the loaded bytes.

concretize_read_addr(addr, strategies=None, condition=None)

Concretizes an address meant for reading.

Parameters:

• addr – An expression for the address.

• strategies – A list of concretization strategies (to override the default).

Returns:

A list of concrete addresses.

concretize_write_addr(addr, strategies=None, condition=None)

Concretizes an address meant for writing.

Parameters:

• addr – An expression for the address.

• strategies – A list of concretization strategies (to override the default).

• condition – Any extra constraints that should be observed when determining address satisfiability

Returns:

A list of concrete addresses.

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

dbg_print(indent=0)

Print out debugging information

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, default=None, endness=None, chunk_size=None, max_symbolic_bytes=None, condition=None, char_size=1, **kwargs)

flush_pages(white_list)

Flush all pages not included in the white_list by removing their pages. Note, this will not wipe them from memory if they were backed by a memory_backer, it will simply reset them to their initial state. Returns the list of pages that were cleared consisting of (addr, length) tuples. :type white_list: :param white_list: white list of regions in the form of (start, end) to exclude from the flush :return: a list of memory page ranges that were flushed :rtype: list

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.

get_symbolic_addrs()

init_state()

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

property is_stack

load(addr, size=None, bbl_addr=None, stmt_idx=None, ins_addr=None, **kwargs)

map_region(addr, length, permissions, **kwargs)

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

property related_function_addr

replace_all(old, new)

Replaces all instances of expression old with expression new.

Parameters:

• old (BV) – A claripy expression. Must contain at least one named variable (to make it possible to use the name index for speedup).

• new (BV) – The new variable to replace it with.

set_state(state)

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

set_strongref_state(state)

store(addr, data, bbl_addr=None, stmt_id=None, ins_addr=None, endness=None, **kwargs)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.LabeledMemory(*args, top_func=None, **kwargs)

Bases: SizeNormalizationMixin, ListPagesWithLabelsMixin, DefaultFillerMixin, TopMergerMixin, LabelMergerMixin, PagedMemoryMixin

LabeledMemory is used in static analysis. It allows storing values with labels, such as Definition.

PAGE_TYPE

alias of ListPage

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = True

__init__(*args, top_func=None, **kwargs)

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

changed_bytes(other)

Return type:

Set[int]

changed_pages(other)

Return type:

Dict[int, Optional[Set[int]]]

concrete_load(addr, size, writing=False, with_bitmap=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Returns:

A memoryview into the loaded bytes.

copy(memo=None)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

flush_pages(white_list)

Flush all pages not included in the white_list by removing their pages. Note, this will not wipe them from memory if they were backed by a memory_backer, it will simply reset them to their initial state. Returns the list of pages that were cleared consisting of (addr, length) tuples. :type white_list: :param white_list: white list of regions in the form of (start, end) to exclude from the flush :return: a list of memory page ranges that were flushed :rtype: list

init_state()

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

load(addr, size=None, **kwargs)

load_with_labels(addr, size=None, endness=None, **kwargs)

Return type:

Tuple[Base, Tuple[Tuple[int, int, int, Any]]]

Parameters:

• addr (int) –

• size (int | None) –

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

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 (Iterable[PagedMemoryMixin]) – 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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

store(addr, data, size=None, **kwargs)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.MultiValuedMemory(*args, skip_missing_values_during_merging=False, **kwargs)

Bases: SizeNormalizationMixin, MVListPagesMixin, DefaultFillerMixin, MultiValueMergerMixin, PagedMemoryMixin

PAGE_TYPE

alias of MVListPage

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = True

__init__(*args, skip_missing_values_during_merging=False, **kwargs)

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

changed_bytes(other)

Return type:

Set[int]

changed_pages(other)

Return type:

Dict[int, Optional[Set[int]]]

concrete_load(addr, size, writing=False, with_bitmap=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Returns:

A memoryview into the loaded bytes.

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

flush_pages(white_list)

Flush all pages not included in the white_list by removing their pages. Note, this will not wipe them from memory if they were backed by a memory_backer, it will simply reset them to their initial state. Returns the list of pages that were cleared consisting of (addr, length) tuples. :type white_list: :param white_list: white list of regions in the form of (start, end) to exclude from the flush :return: a list of memory page ranges that were flushed :rtype: list

init_state()

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

load(addr, size=None, **kwargs)

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

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 (Iterable[PagedMemoryMixin]) – 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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

store(addr, data, size=None, **kwargs)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.KeyValueMemory(*args, **kwargs)

Bases: KeyValueMemoryMixin

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

__init__(*args, **kwargs)

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

load(key, none_if_missing=False, **kwargs)

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

store(key, data, type_=None, **kwargs)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.JavaVmMemory(memory_id='mem', stack=None, heap=None, vm_static_table=None, load_strategies=None, store_strategies=None, max_array_size=1000, **kwargs)

Bases: JavaVmMemoryMixin

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

__init__(memory_id='mem', stack=None, heap=None, vm_static_table=None, load_strategies=None, store_strategies=None, max_array_size=1000, **kwargs)

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

concretize_load_idx(idx, strategies=None)

Concretizes a load index.

Parameters:

• idx – An expression for the index.

• strategies – A list of concretization strategies (to override the default).

• min_idx – Minimum value for a concretized index (inclusive).

• max_idx – Maximum value for a concretized index (exclusive).

Returns:

A list of concrete indexes.

concretize_store_idx(idx, strategies=None)

Concretizes a store index.

Parameters:

• idx – An expression for the index.

• strategies – A list of concretization strategies (to override the default).

• min_idx – Minimum value for a concretized index (inclusive).

• max_idx – Maximum value for a concretized index (exclusive).

Returns:

A list of concrete indexes.

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

static get_new_uuid()

Generate a unique id within the scope of the JavaVM memory. This, for example, is used for distinguishing memory objects of the same type (e.g. multiple instances of the same class).

init_state()

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

load(addr, frame=0, none_if_missing=False)

load_array_element(array, idx)

load_array_elements(array, start_idx, no_of_elements)

Loads either a single element or a range of elements from the array.

Parameters:

• array – Reference to the array.

• start_idx – Starting index for the load.

• no_of_elements – Number of elements to load.

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

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

permissions(addr, permissions=None, **kwargs)

pop_stack_frame()

push_stack_frame()

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

property stack

store(addr, data, frame=0)

store_array_element(array, idx, value)

store_array_elements(array, start_idx, data)

Stores either a single element or a range of elements in the array.

Parameters:

• array – Reference to the array.

• start_idx – Starting index for the store.

• data – Either a single value or a list of values.

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.name_resolution_mixin.NameResolutionMixin(memory_id=None, endness='Iend_BE')

Bases: MemoryMixin

This mixin allows you to provide register names as load addresses, and will automatically translate this to an offset and size.

store(addr, data, size=None, **kwargs)

load(addr, size=None, **kwargs)

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

__init__(memory_id=None, endness='Iend_BE')

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.smart_find_mixin.SmartFindMixin(memory_id=None, endness='Iend_BE')

Bases: MemoryMixin

find(addr, needle, max_search, default=None, endness=None, chunk_size=None, max_symbolic_bytes=None, condition=None, char_size=1, **kwargs)

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

__init__(memory_id=None, endness='Iend_BE')

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

init_state()

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

load(addr, **kwargs)

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

store(addr, data, **kwargs)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.default_filler_mixin.DefaultFillerMixin(memory_id=None, endness='Iend_BE')

Bases: MemoryMixin

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

__init__(memory_id=None, endness='Iend_BE')

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

load(addr, **kwargs)

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

store(addr, data, **kwargs)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.default_filler_mixin.SpecialFillerMixin(special_memory_filler=None, **kwargs)

Bases: MemoryMixin

__init__(special_memory_filler=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

load(addr, **kwargs)

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

store(addr, data, **kwargs)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.default_filler_mixin.ExplicitFillerMixin(uninitialized_read_handler=None, **kwargs)

Bases: MemoryMixin

__init__(uninitialized_read_handler=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

load(addr, **kwargs)

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

store(addr, data, **kwargs)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.bvv_conversion_mixin.DataNormalizationMixin(memory_id=None, endness='Iend_BE')

Bases: MemoryMixin

Normalizes the data field for a store and the fallback field for a load to be BVs.

store(addr, data, size=None, **kwargs)

load(addr, size=None, fallback=None, **kwargs)

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

__init__(memory_id=None, endness='Iend_BE')

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.hex_dumper_mixin.HexDumperMixin(memory_id=None, endness='Iend_BE')

Bases: MemoryMixin

hex_dump(start, size, word_size=4, words_per_row=4, endianness='Iend_BE', symbolic_char='?', unprintable_char='.', solve=False, extra_constraints=None, inspect=False, disable_actions=True)

Returns a hex dump as a string. The solver, if enabled, is called once for every byte potentially making this function very slow. It is meant to be used mainly as a “visualization” for debugging.

Warning: May read and display more bytes than size due to rounding. Particularly, if size is less than, or not a multiple of word_size*words_per_line.

Parameters:

• start – starting address from which to print

• size – number of bytes to display

• word_size – number of bytes to group together as one space-delimited unit

• words_per_row – number of words to display per row of output

• endianness – endianness to use when displaying each word (ASCII representation is unchanged)

• symbolic_char – the character to display when a byte is symbolic and has multiple solutions

• unprintable_char – the character to display when a byte is not printable

• solve – whether or not to attempt to solve (warning: can be very slow)

• extra_constraints – extra constraints to pass to the solver is solve is True

• inspect – whether or not to trigger SimInspect breakpoints for the memory load

• disable_actions – whether or not to disable SimActions for the memory load

Returns:

hex dump as a string

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

__init__(memory_id=None, endness='Iend_BE')

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

load(addr, **kwargs)

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

store(addr, data, **kwargs)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.underconstrained_mixin.UnderconstrainedMixin(*args, **kwargs)

Bases: MemoryMixin

__init__(*args, **kwargs)

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

load(addr, **kwargs)

store(addr, data, **kwargs)

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.simple_interface_mixin.SimpleInterfaceMixin(memory_id=None, endness='Iend_BE')

Bases: MemoryMixin

load(addr, size=None, endness=None, condition=None, fallback=None, **kwargs)

store(addr, data, size=None, endness=None, condition=None, **kwargs)

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

__init__(memory_id=None, endness='Iend_BE')

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.actions_mixin.ActionsMixinHigh(memory_id=None, endness='Iend_BE')

Bases: MemoryMixin

load(addr, size=None, condition=None, fallback=None, disable_actions=False, action=None, **kwargs)

store(addr, data, size=None, disable_actions=False, action=None, condition=None, **kwargs)

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

__init__(memory_id=None, endness='Iend_BE')

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.actions_mixin.ActionsMixinLow(memory_id=None, endness='Iend_BE')

Bases: MemoryMixin

load(addr, action=None, **kwargs)

store(addr, data, action=None, **kwargs)

Parameters:

action (SimActionData | None) –

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

__init__(memory_id=None, endness='Iend_BE')

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.symbolic_merger_mixin.SymbolicMergerMixin(memory_id=None, endness='Iend_BE')

Bases: MemoryMixin

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

__init__(memory_id=None, endness='Iend_BE')

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

load(addr, **kwargs)

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

store(addr, data, **kwargs)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.size_resolution_mixin.SizeNormalizationMixin(memory_id=None, endness='Iend_BE')

Bases: MemoryMixin

Provides basic services related to normalizing sizes. After this mixin, sizes will always be a plain int. Assumes that the data is a BV.

• load will throw a TypeError if no size is provided

• store will default to len(data)//byte_width if no size is provided

load(addr, size=None, **kwargs)

store(addr, data, size=None, **kwargs)

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

__init__(memory_id=None, endness='Iend_BE')

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.size_resolution_mixin.SizeConcretizationMixin(concretize_symbolic_write_size=False, max_concretize_count=256, max_symbolic_size=4194304, raise_memory_limit_error=False, size_limit=257, **kwargs)

Bases: MemoryMixin

This mixin allows memory to process symbolic sizes. It will not touch any sizes which are not ASTs with non-BVV ops. Assumes that the data is a BV.

• symbolic load sizes will be concretized as their maximum and a warning will be logged

• symbolic store sizes will be dispatched as several conditional stores with concrete sizes

Parameters:

• concretize_symbolic_write_size (bool) –

• max_concretize_count (int | None) –

• max_symbolic_size (int) –

• raise_memory_limit_error (bool) –

• size_limit (int) –

__init__(concretize_symbolic_write_size=False, max_concretize_count=256, max_symbolic_size=4194304, raise_memory_limit_error=False, size_limit=257, **kwargs)

Parameters:

• concretize_symbolic_write_size (bool) –

• max_concretize_count (int | None) –

• max_symbolic_size (int) –

• raise_memory_limit_error (bool) –

• size_limit (int) –

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

load(addr, size=None, **kwargs)

store(addr, data, size=None, condition=None, **kwargs)

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.dirty_addrs_mixin.DirtyAddrsMixin(memory_id=None, endness='Iend_BE')

Bases: MemoryMixin

store(addr, data, size=None, **kwargs)

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

__init__(memory_id=None, endness='Iend_BE')

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

load(addr, **kwargs)

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.address_concretization_mixin.MultiwriteAnnotation

Bases: Annotation

property eliminatable

Returns whether this annotation can be eliminated in a simplification.

Returns:

True if eliminatable, False otherwise

property relocateable

property relocatable

Returns whether this annotation can be relocated in a simplification.

Returns:

True if it can be relocated, false otherwise.

relocate(src, dst)

This is called when an annotation has to be relocated because of simplifications.

Consider the following case:

x = claripy.BVS(‘x’, 32) zero = claripy.BVV(0, 32).add_annotation(your_annotation) y = x + zero

Here, one of three things can happen:

1. if your_annotation.eliminatable is True, the simplifiers will simply eliminate your_annotation along with zero and y is x will hold

2. elif your_annotation.relocatable is False, the simplifier will abort and y will never be simplified

3. elif your_annotation.relocatable is True, the simplifier will run, determine that the simplified result of x + zero will be x. It will then call your_annotation.relocate(zero, x) to move the annotation away from the AST that is about to be eliminated.

Parameters:

• src – the old AST that was eliminated in the simplification

• dst – the new AST (the result of a simplification)

Returns:

the annotation that will be applied to dst

class angr.storage.memory_mixins.address_concretization_mixin.AddressConcretizationMixin(read_strategies=None, write_strategies=None, **kwargs)

Bases: MemoryMixin

The address concretization mixin allows symbolic reads and writes to be handled sanely by dispatching them as a number of conditional concrete reads/writes. It provides a “concretization strategies” interface allowing the process of serializing symbolic addresses into concrete ones to be specified.

__init__(read_strategies=None, write_strategies=None, **kwargs)

set_state(state)

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

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

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

concretize_write_addr(addr, strategies=None, condition=None)

Concretizes an address meant for writing.

Parameters:

• addr – An expression for the address.

• strategies – A list of concretization strategies (to override the default).

• condition – Any extra constraints that should be observed when determining address satisfiability

Returns:

A list of concrete addresses.

concretize_read_addr(addr, strategies=None, condition=None)

Concretizes an address meant for reading.

Parameters:

• addr – An expression for the address.

• strategies – A list of concretization strategies (to override the default).

Returns:

A list of concrete addresses.

load(addr, size=None, condition=None, **kwargs)

store(addr, data, size=None, condition=None, **kwargs)

permissions(addr, permissions=None, **kwargs)

map_region(addr, length, permissions, **kwargs)

unmap_region(addr, length, **kwargs)

concrete_load(addr, size, *args, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Returns:

A memoryview into the loaded bytes.

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

static memo(f)

A decorator function you should apply to copy

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_strongref_state(state)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.clouseau_mixin.InspectMixinHigh(memory_id=None, endness='Iend_BE')

Bases: MemoryMixin

store(addr, data, size=None, condition=None, endness=None, inspect=True, **kwargs)

load(addr, size=None, condition=None, endness=None, inspect=True, **kwargs)

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

__init__(memory_id=None, endness='Iend_BE')

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.conditional_store_mixin.ConditionalMixin(memory_id=None, endness='Iend_BE')

Bases: MemoryMixin

load(addr, condition=None, fallback=None, **kwargs)

store(addr, data, size=None, condition=None, **kwargs)

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

__init__(memory_id=None, endness='Iend_BE')

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.label_merger_mixin.LabelMergerMixin(*args, **kwargs)

Bases: MemoryMixin

A memory mixin for merging labels. Labels come from SimLabeledMemoryObject.

__init__(*args, **kwargs)

copy(memo=None)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

load(addr, **kwargs)

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

store(addr, data, **kwargs)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.simplification_mixin.SimplificationMixin(memory_id=None, endness='Iend_BE')

Bases: MemoryMixin

store(addr, data, **kwargs)

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

__init__(memory_id=None, endness='Iend_BE')

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

load(addr, **kwargs)

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.unwrapper_mixin.UnwrapperMixin(memory_id=None, endness='Iend_BE')

Bases: MemoryMixin

This mixin processes SimActionObjects by passing on their .ast field.

store(addr, data, size=None, condition=None, **kwargs)

load(addr, size=None, condition=None, fallback=None, **kwargs)

find(addr, what, max_search, default=None, **kwargs)

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

__init__(memory_id=None, endness='Iend_BE')

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

init_state()

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

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.convenient_mappings_mixin.ConvenientMappingsMixin(**kwargs)

Bases: MemoryMixin

Implements mappings between names and hashes of symbolic variables and these variables themselves.

__init__(**kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

store(addr, data, size=None, **kwargs)

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.

replace_all(old, new)

Replaces all instances of expression old with expression new.

Parameters:

• old (BV) – A claripy expression. Must contain at least one named variable (to make it possible to use the name index for speedup).

• new (BV) – The new variable to replace it with.

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

load(addr, **kwargs)

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

set_state(state)

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

set_strongref_state(state)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.paged_memory.pages.mv_list_page.MVListPage(memory=None, content=None, sinkhole=None, mo_cmp=None, **kwargs)

Bases: MemoryObjectSetMixin, PageBase

MVListPage allows storing multiple values at the same location, thus allowing weak updates.

Each store() may take a value or multiple values, and a “weak” parameter to specify if this store is a weak update or not. Each load() returns an iterator of all values stored at that location.

__init__(memory=None, content=None, sinkhole=None, mo_cmp=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

Return type:

MVListPage

load(addr, size=None, endness=None, page_addr=None, memory=None, cooperate=False, **kwargs)

Return type:

List[Tuple[int, Union[SimMemoryObject, SimLabeledMemoryObject]]]

store(addr, data, size=None, endness=None, memory=None, cooperate=False, weak=False, **kwargs)

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

merge(others, merge_conditions, common_ancestor=None, page_addr=None, memory=None, changed_offsets=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 (List[MVListPage]) – 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

• page_addr (int | None) –

• changed_offsets (Set[int] | None) –

Returns:

True if the state plugins are actually merged.

Return type:

bool

changed_bytes(other, page_addr=None)

Parameters:

• other (MVListPage) –

• page_addr (int | None) –

content_gen(index)

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

acquire_shared()

Call this function to indicate that this page has had a reference added to it and must be copied before it can be acquired uniquely again. Creating the object implicitly starts it with one shared reference.

Return type:

None

acquire_unique()

Call this function to return a version of this page which can be used for writing, which may or may not be the same object as before. If you use this you must immediately replace the shared reference you previously had with the new unique copy.

all_bytes_changed_in_history()

Return type:

Set[int]

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

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

static memo(f)

A decorator function you should apply to copy

parents()

property perm_exec

property perm_read

property perm_write

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

release_shared()

Call this function to indicate that this page has had a shared reference to it released

Return type:

None

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.paged_memory.pages.multi_values.MultiValues(v=None, offset_to_values=None)

Bases: object

Represents a byte vector where each byte can have one or multiple values.

As an implementation optimization (so that we do not create excessive sets and dicts), self._single_value stores a claripy AST when this MultiValues object represents only one value at offset 0.

Parameters:

v (Base | None) –

__init__(v=None, offset_to_values=None)

Parameters:

v (Base | None) –

add_value(offset, value)

Return type:

None

Parameters:

• offset (int) –

• value (Base) –

one_value()

Return type:

Optional[Base]

merge(mv)

Return type:

MultiValues

Parameters:

mv (MultiValues) –

keys()

Return type:

Set[int]

values()

Return type:

Iterator[Set[Base]]

items()

Return type:

Iterator[Tuple[int, Set[Base]]]

count()

Return type:

int

class angr.storage.memory_mixins.top_merger_mixin.TopMergerMixin(*args, top_func=None, **kwargs)

Bases: MemoryMixin

A memory mixin for merging values in memory to TOP.

__init__(*args, top_func=None, **kwargs)

copy(memo=None)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

load(addr, **kwargs)

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

store(addr, data, **kwargs)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.multi_value_merger_mixin.MultiValueMergerMixin(*args, element_limit=5, top_func=None, phi_maker=None, **kwargs)

Bases: MemoryMixin

__init__(*args, element_limit=5, top_func=None, phi_maker=None, **kwargs)

copy(memo=None)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

load(addr, **kwargs)

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

store(addr, data, **kwargs)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.paged_memory.paged_memory_mixin.PagedMemoryMixin(page_size=4096, default_permissions=3, permissions_map=None, page_kwargs=None, **kwargs)

Bases: MemoryMixin

A bottom-level storage mechanism. Dispatches reads to individual pages, the type of which is the PAGE_TYPE class variable.

SUPPORTS_CONCRETE_LOAD = True

PAGE_TYPE: Type[TypeVar(PageType, bound= PageBase)] = None

__init__(page_size=4096, default_permissions=3, permissions_map=None, page_kwargs=None, **kwargs)

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

load(addr, size=None, endness=None, **kwargs)

Parameters:

• addr (int) –

• size (int | None) –

store(addr, data, size=None, endness=None, **kwargs)

Parameters:

• addr (int) –

• size (int | None) –

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

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 (Iterable[PagedMemoryMixin]) – 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

permissions(addr, permissions=None, **kwargs)

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

unmap_region(addr, length, **kwargs)

concrete_load(addr, size, writing=False, with_bitmap=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Returns:

A memoryview into the loaded bytes.

changed_bytes(other)

Return type:

Set[int]

changed_pages(other)

Return type:

Dict[int, Optional[Set[int]]]

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

flush_pages(white_list)

Flush all pages not included in the white_list by removing their pages. Note, this will not wipe them from memory if they were backed by a memory_backer, it will simply reset them to their initial state. Returns the list of pages that were cleared consisting of (addr, length) tuples. :type white_list: :param white_list: white list of regions in the form of (start, end) to exclude from the flush :return: a list of memory page ranges that were flushed :rtype: list

STRONGREF_STATE = False

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

find(addr, data, max_search, **kwargs)

init_state()

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

static memo(f)

A decorator function you should apply to copy

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.paged_memory.paged_memory_mixin.LabeledPagesMixin(page_size=4096, default_permissions=3, permissions_map=None, page_kwargs=None, **kwargs)

Bases: PagedMemoryMixin

load_with_labels(addr, size=None, endness=None, **kwargs)

Return type:

Tuple[Base, Tuple[Tuple[int, int, int, Any]]]

Parameters:

• addr (int) –

• size (int | None) –

PAGE_TYPE: Type[TypeVar(PageType, bound= PageBase)] = None

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = True

__init__(page_size=4096, default_permissions=3, permissions_map=None, page_kwargs=None, **kwargs)

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

changed_bytes(other)

Return type:

Set[int]

changed_pages(other)

Return type:

Dict[int, Optional[Set[int]]]

concrete_load(addr, size, writing=False, with_bitmap=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Returns:

A memoryview into the loaded bytes.

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

flush_pages(white_list)

Flush all pages not included in the white_list by removing their pages. Note, this will not wipe them from memory if they were backed by a memory_backer, it will simply reset them to their initial state. Returns the list of pages that were cleared consisting of (addr, length) tuples. :type white_list: :param white_list: white list of regions in the form of (start, end) to exclude from the flush :return: a list of memory page ranges that were flushed :rtype: list

init_state()

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

load(addr, size=None, endness=None, **kwargs)

Parameters:

• addr (int) –

• size (int | None) –

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

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 (Iterable[PagedMemoryMixin]) – 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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

store(addr, data, size=None, endness=None, **kwargs)

Parameters:

• addr (int) –

• size (int | None) –

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.paged_memory.paged_memory_mixin.ListPagesMixin(page_size=4096, default_permissions=3, permissions_map=None, page_kwargs=None, **kwargs)

Bases: PagedMemoryMixin

PAGE_TYPE

alias of ListPage

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = True

__init__(page_size=4096, default_permissions=3, permissions_map=None, page_kwargs=None, **kwargs)

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

changed_bytes(other)

Return type:

Set[int]

changed_pages(other)

Return type:

Dict[int, Optional[Set[int]]]

concrete_load(addr, size, writing=False, with_bitmap=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Returns:

A memoryview into the loaded bytes.

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

flush_pages(white_list)

Flush all pages not included in the white_list by removing their pages. Note, this will not wipe them from memory if they were backed by a memory_backer, it will simply reset them to their initial state. Returns the list of pages that were cleared consisting of (addr, length) tuples. :type white_list: :param white_list: white list of regions in the form of (start, end) to exclude from the flush :return: a list of memory page ranges that were flushed :rtype: list

init_state()

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

load(addr, size=None, endness=None, **kwargs)

Parameters:

• addr (int) –

• size (int | None) –

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

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 (Iterable[PagedMemoryMixin]) – 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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

store(addr, data, size=None, endness=None, **kwargs)

Parameters:

• addr (int) –

• size (int | None) –

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.paged_memory.paged_memory_mixin.MVListPagesMixin(*args, skip_missing_values_during_merging=False, **kwargs)

Bases: PagedMemoryMixin

PAGE_TYPE

alias of MVListPage

__init__(*args, skip_missing_values_during_merging=False, **kwargs)

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = True

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

changed_bytes(other)

Return type:

Set[int]

changed_pages(other)

Return type:

Dict[int, Optional[Set[int]]]

concrete_load(addr, size, writing=False, with_bitmap=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Returns:

A memoryview into the loaded bytes.

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

flush_pages(white_list)

Flush all pages not included in the white_list by removing their pages. Note, this will not wipe them from memory if they were backed by a memory_backer, it will simply reset them to their initial state. Returns the list of pages that were cleared consisting of (addr, length) tuples. :type white_list: :param white_list: white list of regions in the form of (start, end) to exclude from the flush :return: a list of memory page ranges that were flushed :rtype: list

init_state()

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

load(addr, size=None, endness=None, **kwargs)

Parameters:

• addr (int) –

• size (int | None) –

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

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 (Iterable[PagedMemoryMixin]) – 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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

store(addr, data, size=None, endness=None, **kwargs)

Parameters:

• addr (int) –

• size (int | None) –

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.paged_memory.paged_memory_mixin.ListPagesWithLabelsMixin(page_size=4096, default_permissions=3, permissions_map=None, page_kwargs=None, **kwargs)

Bases: LabeledPagesMixin, ListPagesMixin

PAGE_TYPE

alias of ListPage

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = True

__init__(page_size=4096, default_permissions=3, permissions_map=None, page_kwargs=None, **kwargs)

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

changed_bytes(other)

Return type:

Set[int]

changed_pages(other)

Return type:

Dict[int, Optional[Set[int]]]

concrete_load(addr, size, writing=False, with_bitmap=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Returns:

A memoryview into the loaded bytes.

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

flush_pages(white_list)

Flush all pages not included in the white_list by removing their pages. Note, this will not wipe them from memory if they were backed by a memory_backer, it will simply reset them to their initial state. Returns the list of pages that were cleared consisting of (addr, length) tuples. :type white_list: :param white_list: white list of regions in the form of (start, end) to exclude from the flush :return: a list of memory page ranges that were flushed :rtype: list

init_state()

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

load(addr, size=None, endness=None, **kwargs)

Parameters:

• addr (int) –

• size (int | None) –

load_with_labels(addr, size=None, endness=None, **kwargs)

Return type:

Tuple[Base, Tuple[Tuple[int, int, int, Any]]]

Parameters:

• addr (int) –

• size (int | None) –

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

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 (Iterable[PagedMemoryMixin]) – 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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

store(addr, data, size=None, endness=None, **kwargs)

Parameters:

• addr (int) –

• size (int | None) –

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.paged_memory.paged_memory_mixin.MVListPagesWithLabelsMixin(*args, skip_missing_values_during_merging=False, **kwargs)

Bases: LabeledPagesMixin, MVListPagesMixin

PAGE_TYPE

alias of MVListPage

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = True

__init__(*args, skip_missing_values_during_merging=False, **kwargs)

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

changed_bytes(other)

Return type:

Set[int]

changed_pages(other)

Return type:

Dict[int, Optional[Set[int]]]

concrete_load(addr, size, writing=False, with_bitmap=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Returns:

A memoryview into the loaded bytes.

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

flush_pages(white_list)

Flush all pages not included in the white_list by removing their pages. Note, this will not wipe them from memory if they were backed by a memory_backer, it will simply reset them to their initial state. Returns the list of pages that were cleared consisting of (addr, length) tuples. :type white_list: :param white_list: white list of regions in the form of (start, end) to exclude from the flush :return: a list of memory page ranges that were flushed :rtype: list

init_state()

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

load(addr, size=None, endness=None, **kwargs)

Parameters:

• addr (int) –

• size (int | None) –

load_with_labels(addr, size=None, endness=None, **kwargs)

Return type:

Tuple[Base, Tuple[Tuple[int, int, int, Any]]]

Parameters:

• addr (int) –

• size (int | None) –

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

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 (Iterable[PagedMemoryMixin]) – 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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

store(addr, data, size=None, endness=None, **kwargs)

Parameters:

• addr (int) –

• size (int | None) –

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.paged_memory.paged_memory_mixin.UltraPagesMixin(page_size=4096, default_permissions=3, permissions_map=None, page_kwargs=None, **kwargs)

Bases: PagedMemoryMixin

PAGE_TYPE

alias of UltraPage

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = True

__init__(page_size=4096, default_permissions=3, permissions_map=None, page_kwargs=None, **kwargs)

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

changed_bytes(other)

Return type:

Set[int]

changed_pages(other)

Return type:

Dict[int, Optional[Set[int]]]

concrete_load(addr, size, writing=False, with_bitmap=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Returns:

A memoryview into the loaded bytes.

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

flush_pages(white_list)

Flush all pages not included in the white_list by removing their pages. Note, this will not wipe them from memory if they were backed by a memory_backer, it will simply reset them to their initial state. Returns the list of pages that were cleared consisting of (addr, length) tuples. :type white_list: :param white_list: white list of regions in the form of (start, end) to exclude from the flush :return: a list of memory page ranges that were flushed :rtype: list

init_state()

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

load(addr, size=None, endness=None, **kwargs)

Parameters:

• addr (int) –

• size (int | None) –

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

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 (Iterable[PagedMemoryMixin]) – 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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

store(addr, data, size=None, endness=None, **kwargs)

Parameters:

• addr (int) –

• size (int | None) –

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.paged_memory.page_backer_mixins.NotMemoryview(obj, offset, size)

Bases: object

__init__(obj, offset, size)

class angr.storage.memory_mixins.paged_memory.page_backer_mixins.ClemoryBackerMixin(cle_memory_backer=None, **kwargs)

Bases: PagedMemoryMixin

Parameters:

cle_memory_backer (None | Loader | Clemory) –

__init__(cle_memory_backer=None, **kwargs)

Parameters:

cle_memory_backer (None | Loader | Clemory) –

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

PAGE_TYPE: Type[TypeVar(PageType, bound= PageBase)] = None

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = True

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

changed_bytes(other)

Return type:

Set[int]

changed_pages(other)

Return type:

Dict[int, Optional[Set[int]]]

concrete_load(addr, size, writing=False, with_bitmap=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Returns:

A memoryview into the loaded bytes.

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

flush_pages(white_list)

Flush all pages not included in the white_list by removing their pages. Note, this will not wipe them from memory if they were backed by a memory_backer, it will simply reset them to their initial state. Returns the list of pages that were cleared consisting of (addr, length) tuples. :type white_list: :param white_list: white list of regions in the form of (start, end) to exclude from the flush :return: a list of memory page ranges that were flushed :rtype: list

init_state()

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

load(addr, size=None, endness=None, **kwargs)

Parameters:

• addr (int) –

• size (int | None) –

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

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 (Iterable[PagedMemoryMixin]) – 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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

store(addr, data, size=None, endness=None, **kwargs)

Parameters:

• addr (int) –

• size (int | None) –

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.paged_memory.page_backer_mixins.ConcreteBackerMixin(cle_memory_backer=None, **kwargs)

Bases: ClemoryBackerMixin

Parameters:

cle_memory_backer (None | Loader | Clemory) –

PAGE_TYPE: Type[TypeVar(PageType, bound= PageBase)] = None

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = True

__init__(cle_memory_backer=None, **kwargs)

Parameters:

cle_memory_backer (None | Loader | Clemory) –

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

changed_bytes(other)

Return type:

Set[int]

changed_pages(other)

Return type:

Dict[int, Optional[Set[int]]]

concrete_load(addr, size, writing=False, with_bitmap=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Returns:

A memoryview into the loaded bytes.

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

flush_pages(white_list)

Flush all pages not included in the white_list by removing their pages. Note, this will not wipe them from memory if they were backed by a memory_backer, it will simply reset them to their initial state. Returns the list of pages that were cleared consisting of (addr, length) tuples. :type white_list: :param white_list: white list of regions in the form of (start, end) to exclude from the flush :return: a list of memory page ranges that were flushed :rtype: list

init_state()

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

load(addr, size=None, endness=None, **kwargs)

Parameters:

• addr (int) –

• size (int | None) –

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

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 (Iterable[PagedMemoryMixin]) – 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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

store(addr, data, size=None, endness=None, **kwargs)

Parameters:

• addr (int) –

• size (int | None) –

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.paged_memory.page_backer_mixins.DictBackerMixin(dict_memory_backer=None, **kwargs)

Bases: PagedMemoryMixin

PAGE_TYPE: Type[TypeVar(PageType, bound= PageBase)] = None

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = True

__init__(dict_memory_backer=None, **kwargs)

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

changed_bytes(other)

Return type:

Set[int]

changed_pages(other)

Return type:

Dict[int, Optional[Set[int]]]

concrete_load(addr, size, writing=False, with_bitmap=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Returns:

A memoryview into the loaded bytes.

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

flush_pages(white_list)

Flush all pages not included in the white_list by removing their pages. Note, this will not wipe them from memory if they were backed by a memory_backer, it will simply reset them to their initial state. Returns the list of pages that were cleared consisting of (addr, length) tuples. :type white_list: :param white_list: white list of regions in the form of (start, end) to exclude from the flush :return: a list of memory page ranges that were flushed :rtype: list

init_state()

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

load(addr, size=None, endness=None, **kwargs)

Parameters:

• addr (int) –

• size (int | None) –

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

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 (Iterable[PagedMemoryMixin]) – 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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

store(addr, data, size=None, endness=None, **kwargs)

Parameters:

• addr (int) –

• size (int | None) –

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

class angr.storage.memory_mixins.paged_memory.stack_allocation_mixin.StackAllocationMixin(stack_end=None, stack_size=None, stack_perms=None, **kwargs)

Bases: PagedMemoryMixin

This mixin adds automatic allocation for a stack region based on the stack_end and stack_size parameters.

__init__(stack_end=None, stack_size=None, stack_perms=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

allocate_stack_pages(addr, size, **kwargs)

Pre-allocates pages for the stack without triggering any logic related to reading from them.

Parameters:

• addr (int) – The highest address that should be mapped

• size (int) – The number of bytes to be allocated. byte 1 is the one at addr, byte 2 is the one before that, and so on.

Returns:

A list of the new page objects

PAGE_TYPE: Type[TypeVar(PageType, bound= PageBase)] = None

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = True

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

changed_bytes(other)

Return type:

Set[int]

changed_pages(other)

Return type:

Dict[int, Optional[Set[int]]]

concrete_load(addr, size, writing=False, with_bitmap=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Returns:

A memoryview into the loaded bytes.

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

flush_pages(white_list)

Flush all pages not included in the white_list by removing their pages. Note, this will not wipe them from memory if they were backed by a memory_backer, it will simply reset them to their initial state. Returns the list of pages that were cleared consisting of (addr, length) tuples. :type white_list: :param white_list: white list of regions in the form of (start, end) to exclude from the flush :return: a list of memory page ranges that were flushed :rtype: list

init_state()

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

load(addr, size=None, endness=None, **kwargs)

Parameters:

• addr (int) –

• size (int | None) –

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

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 (Iterable[PagedMemoryMixin]) – 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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

store(addr, data, size=None, endness=None, **kwargs)

Parameters:

• addr (int) –

• size (int | None) –

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.paged_memory.privileged_mixin.PrivilegedPagingMixin(page_size=4096, default_permissions=3, permissions_map=None, page_kwargs=None, **kwargs)

Bases: PagedMemoryMixin

A mixin for paged memory models which will raise SimSegfaultExceptions if STRICT_PAGE_ACCESS is enabled and a segfault condition is detected.

Segfault conditions include: - getting a page for reading which is non-readable - getting a page for writing which is non-writable - creating a page

The latter condition means that this should be inserted under any mixins which provide other implementations of _initialize_page.

PAGE_TYPE: Type[TypeVar(PageType, bound= PageBase)] = None

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = True

__init__(page_size=4096, default_permissions=3, permissions_map=None, page_kwargs=None, **kwargs)

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

changed_bytes(other)

Return type:

Set[int]

changed_pages(other)

Return type:

Dict[int, Optional[Set[int]]]

concrete_load(addr, size, writing=False, with_bitmap=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Returns:

A memoryview into the loaded bytes.

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

flush_pages(white_list)

Flush all pages not included in the white_list by removing their pages. Note, this will not wipe them from memory if they were backed by a memory_backer, it will simply reset them to their initial state. Returns the list of pages that were cleared consisting of (addr, length) tuples. :type white_list: :param white_list: white list of regions in the form of (start, end) to exclude from the flush :return: a list of memory page ranges that were flushed :rtype: list

init_state()

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

load(addr, size=None, endness=None, **kwargs)

Parameters:

• addr (int) –

• size (int | None) –

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

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 (Iterable[PagedMemoryMixin]) – 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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

store(addr, data, size=None, endness=None, **kwargs)

Parameters:

• addr (int) –

• size (int | None) –

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.paged_memory.pages.PageBase(*args, **kwargs)

Bases: HistoryTrackingMixin, RefcountMixin, CooperationBase, ISPOMixin, PermissionsMixin, MemoryMixin

This is a fairly succinct definition of the contract between PagedMemoryMixin and its constituent pages:

• Pages must implement the MemoryMixin model for loads, stores, copying, merging, etc

• However, loading/storing may not necessarily use the same data domain as PagedMemoryMixin. In order to do more efficient loads/stores across pages, we use the CooperationBase interface which allows the page class to determine how to generate and unwrap the objects which are actually stored.

• To support COW, we use the RefcountMixin and the ISPOMixin (which adds the contract element that memory=self be passed to every method call)

• Pages have permissions associated with them, stored in the PermissionsMixin.

Read the docstrings for each of the constituent classes to understand the nuances of their functionalities

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

__init__(*args, **kwargs)

acquire_shared()

Call this function to indicate that this page has had a reference added to it and must be copied before it can be acquired uniquely again. Creating the object implicitly starts it with one shared reference.

Return type:

None

acquire_unique()

Call this function to return a version of this page which can be used for writing, which may or may not be the same object as before. If you use this you must immediately replace the shared reference you previously had with the new unique copy.

all_bytes_changed_in_history()

Return type:

Set[int]

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

changed_bytes(other, **kwargs)

Return type:

Optional[Set[int]]

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

load(addr, **kwargs)

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

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

parents()

property perm_exec

property perm_read

property perm_write

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

release_shared()

Call this function to indicate that this page has had a shared reference to it released

Return type:

None

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

store(addr, data, size=None, **kwargs)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.paged_memory.pages.refcount_mixin.RefcountMixin(**kwargs)

Bases: MemoryMixin

This mixin adds a locked reference counter and methods to manipulate it, to facilitate copy-on-write optimizations.

__init__(**kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

acquire_unique()

Call this function to return a version of this page which can be used for writing, which may or may not be the same object as before. If you use this you must immediately replace the shared reference you previously had with the new unique copy.

acquire_shared()

Call this function to indicate that this page has had a reference added to it and must be copied before it can be acquired uniquely again. Creating the object implicitly starts it with one shared reference.

Return type:

None

release_shared()

Call this function to indicate that this page has had a shared reference to it released

Return type:

None

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

load(addr, **kwargs)

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

store(addr, data, **kwargs)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.paged_memory.pages.permissions_mixin.PermissionsMixin(permissions=None, **kwargs)

Bases: MemoryMixin

This mixin adds a permissions field and properties for extracting the read/write/exec permissions. It does NOT add permissions checking.

__init__(permissions=None, **kwargs)

permissions(addr, permissions=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

property perm_read

property perm_write

property perm_exec

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

load(addr, **kwargs)

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

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

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

store(addr, data, **kwargs)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.paged_memory.pages.history_tracking_mixin.HistoryTrackingMixin(*args, **kwargs)

Bases: RefcountMixin, MemoryMixin

Tracks the history of memory writes.

__init__(*args, **kwargs)

store(addr, data, size=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

acquire_unique()

Call this function to return a version of this page which can be used for writing, which may or may not be the same object as before. If you use this you must immediately replace the shared reference you previously had with the new unique copy.

parents()

changed_bytes(other, **kwargs)

Return type:

Optional[Set[int]]

all_bytes_changed_in_history()

Return type:

Set[int]

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

acquire_shared()

Call this function to indicate that this page has had a reference added to it and must be copied before it can be acquired uniquely again. Creating the object implicitly starts it with one shared reference.

Return type:

None

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

load(addr, **kwargs)

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

release_shared()

Call this function to indicate that this page has had a shared reference to it released

Return type:

None

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.paged_memory.pages.ispo_mixin.ISPOMixin(memory_id=None, endness='Iend_BE')

Bases: MemoryMixin

An implementation of the International Stateless Persons Organisation, a mixin which should be applied as a bottom layer for memories which have no state and must redirect certain operations to a parent memory. Main usecase is for memory region classes which are stored within other memories, such as pages.

set_state(state)

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

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

__init__(memory_id=None, endness='Iend_BE')

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

load(addr, **kwargs)

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_strongref_state(state)

store(addr, data, **kwargs)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.paged_memory.pages.cooperation.CooperationBase

Bases: object

Any given subclass of this class which is not a subclass of MemoryMixin should have the property that any subclass it which is a subclass of MemoryMixin should all work with the same datatypes

class angr.storage.memory_mixins.paged_memory.pages.cooperation.MemoryObjectMixin

Bases: CooperationBase

Uses SimMemoryObjects in region storage. With this, load will return a list of tuple (address, MO) and store will take a MO.

class angr.storage.memory_mixins.paged_memory.pages.cooperation.MemoryObjectSetMixin

Bases: CooperationBase

Uses sets of SimMemoryObjects in region storage.

class angr.storage.memory_mixins.paged_memory.pages.cooperation.BasicClaripyCooperation

Bases: CooperationBase

Mix this (along with PageBase) into a storage class which supports loading and storing claripy bitvectors and it will be able to work as a page in the paged memory model.

class angr.storage.memory_mixins.paged_memory.pages.list_page.ListPage(memory=None, content=None, sinkhole=None, mo_cmp=None, **kwargs)

Bases: MemoryObjectMixin, PageBase

This class implements a page memory mixin with lists as the main content store.

__init__(memory=None, content=None, sinkhole=None, mo_cmp=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

load(addr, size=None, endness=None, page_addr=None, memory=None, cooperate=False, **kwargs)

store(addr, data, size=None, endness=None, memory=None, cooperate=False, **kwargs)

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

merge(others, merge_conditions, common_ancestor=None, page_addr=None, memory=None, changed_offsets=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 (List[ListPage]) – 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

• page_addr (int | None) –

• changed_offsets (Set[int] | None) –

Returns:

True if the state plugins are actually merged.

Return type:

bool

changed_bytes(other, page_addr=None)

Parameters:

• other (ListPage) –

• page_addr (int | None) –

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

acquire_shared()

Call this function to indicate that this page has had a reference added to it and must be copied before it can be acquired uniquely again. Creating the object implicitly starts it with one shared reference.

Return type:

None

acquire_unique()

Call this function to return a version of this page which can be used for writing, which may or may not be the same object as before. If you use this you must immediately replace the shared reference you previously had with the new unique copy.

all_bytes_changed_in_history()

Return type:

Set[int]

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

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

static memo(f)

A decorator function you should apply to copy

parents()

property perm_exec

property perm_read

property perm_write

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

release_shared()

Call this function to indicate that this page has had a shared reference to it released

Return type:

None

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.paged_memory.pages.ultra_page.UltraPage(memory=None, init_zero=False, **kwargs)

Bases: MemoryObjectMixin, PageBase

Default page implementation

SUPPORTS_CONCRETE_LOAD = True

__init__(memory=None, init_zero=False, **kwargs)

classmethod new_from_shared(data, memory=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

load(addr, size=None, page_addr=None, endness=None, memory=None, cooperate=False, **kwargs)

store(addr, data, size=None, endness=None, memory=None, page_addr=None, cooperate=False, **kwargs)

Parameters:

• data (int | SimMemoryObject) –

• size (int | None) –

merge(others, merge_conditions, common_ancestor=None, page_addr=None, memory=None, changed_offsets=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 (List[UltraPage]) – 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

• page_addr (int | None) –

• changed_offsets (Set[int] | None) –

Returns:

True if the state plugins are actually merged.

Return type:

bool

concrete_load(addr, size, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Returns:

A memoryview into the loaded bytes.

changed_bytes(other, page_addr=None)

Return type:

Set[int]

STRONGREF_STATE = False

acquire_shared()

Call this function to indicate that this page has had a reference added to it and must be copied before it can be acquired uniquely again. Creating the object implicitly starts it with one shared reference.

Return type:

None

acquire_unique()

Call this function to return a version of this page which can be used for writing, which may or may not be the same object as before. If you use this you must immediately replace the shared reference you previously had with the new unique copy.

all_bytes_changed_in_history()

Return type:

Set[int]

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

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

static memo(f)

A decorator function you should apply to copy

parents()

property perm_exec

property perm_read

property perm_write

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

release_shared()

Call this function to indicate that this page has had a shared reference to it released

Return type:

None

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

replace_all_with_offsets(offsets, old, new, memory=None)

Parameters:

• offsets (Iterable[int]) –

• old (BV) –

• new (BV) –

class angr.storage.memory_mixins.regioned_memory.regioned_memory_mixin.RegionedMemoryMixin(write_targets_limit=2048, read_targets_limit=4096, stack_region_map=None, generic_region_map=None, stack_size=65536, cle_memory_backer=None, dict_memory_backer=None, regioned_memory_cls=None, **kwargs)

Bases: MemoryMixin

Regioned memory. This mixin manages multiple memory regions. Each address is represented as a tuple of (region ID, offset into the region), which is called a regioned address.

Converting absolute addresses into regioned addresses: We map an absolute address to a region by looking up which region this address belongs to in the region map. Currently this is only enabled for stack. Heap support has not landed yet.

When start analyzing a function, the user should call set_stack_address_mapping() to create a new region mapping. Likewise, when exiting from a function, the user should cancel the previous mapping by calling unset_stack_address_mapping().

Parameters:

• write_targets_limit (int) –

• read_targets_limit (int) –

• stack_region_map (RegionMap | None) –

• generic_region_map (RegionMap | None) –

• stack_size (int) –

• cle_memory_backer (Optional) –

• dict_memory_backer (Dict | None) –

• regioned_memory_cls (type | None) –

__init__(write_targets_limit=2048, read_targets_limit=4096, stack_region_map=None, generic_region_map=None, stack_size=65536, cle_memory_backer=None, dict_memory_backer=None, regioned_memory_cls=None, **kwargs)

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

load(addr, size=None, endness=None, condition=None, **kwargs)

Parameters:

• size (BV | int | None) –

• condition (Bool | None) –

store(addr, data, size=None, endness=None, **kwargs)

Parameters:

size (int | None) –

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 (Iterable[RegionedMemoryMixin]) – 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

find(addr, data, max_search, **kwargs)

Parameters:

addr (int | Bits) –

set_state(state)

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

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

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 (int) – The absolute memory address.

• region_id (str) – The region ID.

• related_function_address (Optional[int]) – Related function address.

unset_stack_address_mapping(absolute_address)

Remove a stack mapping.

Parameters:

absolute_address (int) – An absolute memory address that 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.

Return type:

str

Returns:

ID of the new memory region.

set_stack_size(size)

Parameters:

size (int) –

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

init_state()

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

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

static memo(f)

A decorator function you should apply to copy

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

set_strongref_state(state)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.regioned_memory.region_data.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.

Parameters:

• region (str) –

• region_base_addr (int) –

• is_on_stack (bool) –

• function_address (int | None) –

__init__(region, region_base_addr, address, is_on_stack, function_address)

Constructor for the class AddressWrapper.

Parameters:

• region (str) – 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 (Optional[int]) – Related function address (if any).

region

region_base_addr

address

is_on_stack

function_address

to_valueset(state)

Convert to a ValueSet instance

Parameters:

state – A state

Returns:

The converted ValueSet instance

class angr.storage.memory_mixins.regioned_memory.region_data.RegionDescriptor(region_id, base_address, related_function_address=None)

Bases: object

Descriptor for a memory region ID.

__init__(region_id, base_address, related_function_address=None)

region_id

base_address

related_function_address

class angr.storage.memory_mixins.regioned_memory.region_data.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.

__init__(is_stack)

Constructor

Parameters:

is_stack – Whether this is a region map for stack frames or not. Different strategies apply for stack regions.

property is_empty

property stack_base

property 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_mixins.regioned_memory.region_category_mixin.RegionCategoryMixin(memory_id=None, endness='Iend_BE')

Bases: MemoryMixin

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

__init__(memory_id=None, endness='Iend_BE')

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

load(addr, **kwargs)

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

store(addr, data, **kwargs)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.regioned_memory.static_find_mixin.StaticFindMixin(memory_id=None, endness='Iend_BE')

Bases: SmartFindMixin

Implements data finding for abstract memory.

find(addr, data, max_search, default=None, endness=None, chunk_size=None, max_symbolic_bytes=None, condition=None, char_size=1, **kwargs)

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

__init__(memory_id=None, endness='Iend_BE')

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

init_state()

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

load(addr, **kwargs)

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

store(addr, data, **kwargs)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.regioned_memory.abstract_address_descriptor.AbstractAddressDescriptor

Bases: object

AbstractAddressDescriptor describes a list of region+offset tuples. It provides a convenient way for accessing the cardinality (the total number of addresses) without enumerating or creating all addresses in static mode.

__init__()

property cardinality

add_regioned_address(region, addr)

Parameters:

• region (str) –

• addr (StridedInterval) –

clear()

class angr.storage.memory_mixins.regioned_memory.region_meta_mixin.MemoryRegionMetaMixin(related_function_addr=None, **kwargs)

Bases: MemoryMixin

__init__(related_function_addr=None, **kwargs)

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

property is_stack

property 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.

store(addr, data, bbl_addr=None, stmt_id=None, ins_addr=None, endness=None, **kwargs)

load(addr, size=None, bbl_addr=None, stmt_idx=None, ins_addr=None, **kwargs)

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

dbg_print(indent=0)

Print out debugging information

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

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

static memo(f)

A decorator function you should apply to copy

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

state: angr.SimState

class angr.storage.memory_mixins.regioned_memory.abstract_merger_mixin.AbstractMergerMixin(memory_id=None, endness='Iend_BE')

Bases: MemoryMixin

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

__init__(memory_id=None, endness='Iend_BE')

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

load(addr, **kwargs)

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

store(addr, data, **kwargs)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.regioned_memory.regioned_address_concretization_mixin.RegionedAddressConcretizationMixin(read_strategies=None, write_strategies=None, **kwargs)

Bases: MemoryMixin

__init__(read_strategies=None, write_strategies=None, **kwargs)

set_state(state)

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

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

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

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

load(addr, **kwargs)

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

static memo(f)

A decorator function you should apply to copy

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_strongref_state(state)

store(addr, data, **kwargs)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.slotted_memory.SlottedMemoryMixin(width=None, **kwargs)

Bases: MemoryMixin

__init__(width=None, **kwargs)

set_state(state)

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

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

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

load(addr, size=None, endness=None, **kwargs)

store(addr, data, size=None, endness=None, **kwargs)

changed_bytes(other)

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

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

static memo(f)

A decorator function you should apply to copy

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_strongref_state(state)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.keyvalue_memory.keyvalue_memory_mixin.TypedVariable(type_, value)

Bases: object

__init__(type_, value)

type

value

class angr.storage.memory_mixins.keyvalue_memory.keyvalue_memory_mixin.KeyValueMemoryMixin(*args, **kwargs)

Bases: MemoryMixin

__init__(*args, **kwargs)

load(key, none_if_missing=False, **kwargs)

store(key, data, type_=None, **kwargs)

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

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

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

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_state(state)

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

set_strongref_state(state)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

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

state: angr.SimState

class angr.storage.memory_mixins.javavm_memory.javavm_memory_mixin.JavaVmMemoryMixin(memory_id='mem', stack=None, heap=None, vm_static_table=None, load_strategies=None, store_strategies=None, max_array_size=1000, **kwargs)

Bases: MemoryMixin

__init__(memory_id='mem', stack=None, heap=None, vm_static_table=None, load_strategies=None, store_strategies=None, max_array_size=1000, **kwargs)

static get_new_uuid()

Generate a unique id within the scope of the JavaVM memory. This, for example, is used for distinguishing memory objects of the same type (e.g. multiple instances of the same class).

store(addr, data, frame=0)

load(addr, frame=0, none_if_missing=False)

push_stack_frame()

pop_stack_frame()

property stack

store_array_element(array, idx, value)

store_array_elements(array, start_idx, data)

Stores either a single element or a range of elements in the array.

Parameters:

• array – Reference to the array.

• start_idx – Starting index for the store.

• data – Either a single value or a list of values.

load_array_element(array, idx)

load_array_elements(array, start_idx, no_of_elements)

Loads either a single element or a range of elements from the array.

Parameters:

• array – Reference to the array.

• start_idx – Starting index for the load.

• no_of_elements – Number of elements to load.

concretize_store_idx(idx, strategies=None)

Concretizes a store index.

Parameters:

• idx – An expression for the index.

• strategies – A list of concretization strategies (to override the default).

• min_idx – Minimum value for a concretized index (inclusive).

• max_idx – Maximum value for a concretized index (exclusive).

Returns:

A list of concrete indexes.

concretize_load_idx(idx, strategies=None)

Concretizes a load index.

Parameters:

• idx – An expression for the index.

• strategies – A list of concretization strategies (to override the default).

• min_idx – Minimum value for a concretized index (inclusive).

• max_idx – Maximum value for a concretized index (exclusive).

Returns:

A list of concrete indexes.

set_state(state)

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

copy(memo=None, **kwargs)

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

The base implementation of this function constructs a new instance of the plugin’s class without calling its initializer. If you super-call down to it, make sure you instanciate all the fields in your copy method!

Parameters:

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

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

STRONGREF_STATE = False

SUPPORTS_CONCRETE_LOAD = False

property category

reg, mem, or file.

Type:

Return the category of this SimMemory instance. It can be one of the three following categories

concrete_load(addr, size, writing=False, **kwargs)

Set SUPPORTS_CONCRETE_LOAD to True and implement concrete_load if reading concrete bytes is faster in this memory model.

Parameters:

• addr – The address to load from.

• size – Size of the memory read.

• writing –

Return type:

memoryview

Returns:

A memoryview into the loaded bytes.

copy_contents(dst, src, size, condition=None, **kwargs)

Override this method to provide faster copying of large chunks of data.

Parameters:

• dst – The destination of copying.

• src – The source of copying.

• size – The size of copying.

• condition – The storing condition.

• kwargs – Other parameters.

Returns:

None

erase(addr, size=None, **kwargs)

Set [addr:addr+size) to uninitialized. In many cases this will be faster than overwriting those locations with new values. This is commonly used during static data flow analysis.

Parameters:

• addr – The address to start erasing.

• size – The number of bytes for erasing.

Return type:

None

Returns:

None

find(addr, data, max_search, **kwargs)

init_state()

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

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

static memo(f)

A decorator function you should apply to copy

permissions(addr, permissions=None, **kwargs)

classmethod register_default(name, xtr=None)

replace_all(old, new)

Parameters:

• old (BV) –

• new (BV) –

set_strongref_state(state)

unmap_region(addr, length, **kwargs)

property variable_key_prefix

state: angr.SimState

Concretization Strategies

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

Bases: SimConcretizationStrategy

Concretization strategy that ensures a single solution for an address.

__init__(filter=None, exact=True)

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, **kwargs)

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.

class angr.concretization_strategies.eval.SimConcretizationStrategyEval(limit, **kwargs)

Bases: 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.

__init__(limit, **kwargs)

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, **kwargs)

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.

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

Bases: SimConcretizationStrategy

Concretization strategy that resolves addresses, without repeating.

__init__(repeat_expr, repeat_constraints=None, **kwargs)

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.

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.

concretize(memory, addr, **kwargs)

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

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

Bases: SimConcretizationStrategy

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

__init__(limit, **kwargs)

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, **kwargs)

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.

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

Bases: SimConcretizationStrategy

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

__init__(limit, **kwargs)

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, **kwargs)

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.

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

Bases: SimConcretizationStrategy

Concretization strategy that resolves addresses to a range.

__init__(limit, **kwargs)

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, **kwargs)

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.

class angr.concretization_strategies.max.SimConcretizationStrategyMax(max_addr=None)

Bases: SimConcretizationStrategy

Concretization strategy that returns the maximum address.

Parameters:

max_addr (int | None) –

__init__(max_addr=None)

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.

• max_addr (int | None) –

concretize(memory, addr, **kwargs)

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.

class angr.concretization_strategies.norepeats_range.SimConcretizationStrategyNorepeatsRange(repeat_expr, min=None, granularity=None, **kwargs)

Bases: SimConcretizationStrategy

Concretization strategy that resolves a range, with no repeats.

__init__(repeat_expr, min=None, granularity=None, **kwargs)

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.

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.

concretize(memory, addr, **kwargs)

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

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

Bases: SimConcretizationStrategy

Concretization strategy that returns any non-zero solution.

__init__(filter=None, exact=True)

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, **kwargs)

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.

class angr.concretization_strategies.any.SimConcretizationStrategyAny(filter=None, exact=True)

Bases: SimConcretizationStrategy

Concretization strategy that returns any single solution.

__init__(filter=None, exact=True)

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, **kwargs)

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.

class angr.concretization_strategies.controlled_data.SimConcretizationStrategyControlledData(limit, fixed_addrs, **kwargs)

Bases: SimConcretizationStrategy

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

__init__(limit, fixed_addrs, **kwargs)

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, **kwargs)

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.

class angr.concretization_strategies.unlimited_range.SimConcretizationStrategyUnlimitedRange(limit, **kwargs)

Bases: SimConcretizationStrategy

Concretization strategy that resolves addresses to a range without checking if the number of possible addresses is within the limit.

__init__(limit, **kwargs)

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, **kwargs)

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.

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, suggestions=True, **kwargs)

Bases: object

The Simulation Manager is the future future.

Simulation managers allow you to wrangle multiple states in a slick way. States are organized into “stashes”, which you can step forward, filter, merge, and move around as you wish. This allows you to, for example, step two different stashes of states at different rates, then merge them together.

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

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

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

Parameters:

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

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

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

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

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

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

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

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

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

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

Variables:

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

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

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

ALL = '_ALL'

DROP = '_DROP'

__init__(project, active_states=None, stashes=None, hierarchy=None, resilience=None, save_unsat=False, auto_drop=None, errored=None, completion_mode=<built-in function any>, techniques=None, suggestions=True, **kwargs)

property errored

property stashes: DefaultDict[str, List[SimState]]

mulpyplex(*stashes)

Mulpyplex across several stashes.

Parameters:

stashes – the stashes to mulpyplex

Returns:

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

copy(deep=False)

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

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

use_technique(tech)

Use an exploration technique with this SimulationManager.

Techniques can be found in angr.exploration_techniques.

Parameters:

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

Returns:

The technique that was added, for convenience

remove_technique(tech)

Remove an exploration technique from a list of active techniques.

Parameters:

tech (ExplorationTechnique) – An ExplorationTechnique object.

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

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

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

• An address to find

• A set or list of addresses to find

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

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

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

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

Parameters:

• stash – Operate on this stash

• n – Step at most this many times

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

Returns:

The simulation manager, for chaining.

Return type:

SimulationManager

complete()

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

step(stash='active', target_stash=None, n=None, selector_func=None, step_func=None, error_list=None, successor_func=None, until=None, filter_func=None, **run_args)

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

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

Parameters:

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

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

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

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

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

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

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

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

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

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

Parameters:

• jumpkind – The jumpkind of the previous exit

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

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

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

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

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

• opt_level – The VEX optimization level to use.

• insn_bytes – A string of bytes to use for the block instead of the project.

• size – The maximum size of the block, in bytes.

• num_inst – The maximum number of instructions.

• traceflags – traceflags to be passed to VEX. Default: 0

Returns:

The simulation manager, for chaining.

Return type:

SimulationManager

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

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

filter(state, filter_func=None)

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

selector(state, selector_func=None)

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

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

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

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

Prune unsatisfiable states from a stash.

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

Parameters:

• filter_func – Only prune states that match this filter.

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

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

Returns:

The simulation manager, for chaining.

Return type:

SimulationManager

populate(stash, states)

Populate a stash with a collection of states.

Parameters:

• stash – A stash to populate.

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

absorb(simgr)

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

move(from_stash, to_stash, filter_func=None)

Move states from one stash to another.

Parameters:

• from_stash – Take matching states from this stash.

• to_stash – Put matching states into this stash.

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

Returns:

The simulation manager, for chaining.

Return type:

SimulationManager

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

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

Parameters:

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

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

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

Returns:

The simulation manager, for chaining.

Return type:

SimulationManager

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

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

Parameters:

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

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

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

Returns:

The simulation manager, for chaining.

Return type:

SimulationManager

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

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

Parameters:

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

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

Returns:

The simulation manager, for chaining.

Return type:

SimulationManager

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

Applies a given function to a given stash.

Parameters:

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

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

• stash – A stash to work with.

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

Returns:

The simulation manager, for chaining.

Return type:

SimulationManager

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

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

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

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

The sort done with state_ranker is ascending.

Parameters:

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

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

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

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

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

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

Returns:

The simulation manager, for chaining.

Return type:

SimulationManager

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

Merge the states in a given stash.

Parameters:

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

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

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

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

Returns:

The simulation manager, for chaining.

Return type:

SimulationManager

class angr.sim_manager.ErrorRecord(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.

__init__(state, error, traceback)

debug()

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

reraise()

class angr.state_hierarchy.StateHierarchy

Bases: object

The state hierarchy holds weak references to SimStateHistory objects in a directed acyclic graph. It is useful for queries about a state’s ancestry, notably “what is the best ancestor state for a merge among these states” and “what is the most recent unsatisfiable state while using LAZY_SOLVES”

__init__()

get_ref(obj)

dead_ref(ref)

defer_cleanup()

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: (list of states to merge, those states’ common history, list of states to not merge yet)

Exploration Techniques

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.

__init__()

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.timeout.Timeout(timeout=None)

Bases: ExplorationTechnique

Timeout exploration technique that stops an active exploration if the run time exceeds a predefined timeout

__init__(timeout=None)

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) –

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) –

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) –

class angr.exploration_techniques.dfs.DFS(deferred_stash='deferred')

Bases: 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.

__init__(deferred_stash='deferred')

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) –

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) –

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) –

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: 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.

__init__(find=None, avoid=None, find_stash='found', avoid_stash='avoid', cfg=None, num_find=1, avoid_priority=False)

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.lengthlimiter.LengthLimiter(max_length, drop=False)

Bases: ExplorationTechnique

Length limiter on paths.

__init__(max_length, drop=False)

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) –

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) –

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) –

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_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) –

class angr.exploration_techniques.manual_mergepoint.ManualMergepoint(address, wait_counter=10, prune=True)

Bases: ExplorationTechnique

__init__(address, wait_counter=10, prune=True)

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

mark_nofilter(simgr, stash)

mark_okfilter(simgr, stash)

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) –

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) –

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) –

class angr.exploration_techniques.spiller.PickledStatesBase

Bases: object

The base class of pickled states

sort()

Sort pickled states.

add(prio, sid)

Add a newly pickled state.

Parameters:

• prio (int) – Priority of the state.

• sid (str) – Persistent ID of the state.

Returns:

None

pop_n(n)

Pop the top N states.

Parameters:

n (int) – Number of states to take.

Returns:

A list of states.

class angr.exploration_techniques.spiller.PickledStatesList

Bases: PickledStatesBase

List-backed pickled state storage.

__init__()

sort()

Sort pickled states.

add(prio, sid)

Add a newly pickled state.

Parameters:

• prio (int) – Priority of the state.

• sid (str) – Persistent ID of the state.

Returns:

None

pop_n(n)

Pop the top N states.

Parameters:

n (int) – Number of states to take.

Returns:

A list of states.

class angr.exploration_techniques.spiller.PickledStatesDb(db_str='sqlite:///:memory:')

Bases: PickledStatesBase

Database-backed pickled state storage.

__init__(db_str='sqlite:///:memory:')

sort()

Sort pickled states.

add(prio, sid, taken=False, stash='spilled')

Add a newly pickled state.

Parameters:

• prio (int) – Priority of the state.

• sid (str) – Persistent ID of the state.

Returns:

None

pop_n(n, stash='spilled')

Pop the top N states.

Parameters:

n (int) – Number of states to take.

Returns:

A list of states.

get_recent_n(n, stash='spilled')

count()

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, post_pickle_callback=None, priority_key=None, vault=None, states_collection=None)

Bases: 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.

__init__(src_stash='active', min=5, max=10, staging_stash='spill_stage', staging_min=10, staging_max=20, pickle_callback=None, unpickle_callback=None, post_pickle_callback=None, priority_key=None, vault=None, states_collection=None)

Initializes the spiller.

Parameters:

• max – the number of states that are not spilled

• src_stash – the stash from which to spill states (default: active)

• staging_stash – the stash to which to spill states (default: “spill_stage”)

• 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).

• priority_key – a function that takes a state and returns its numerical priority (MAX_INT is lowest priority). By default, self.state_priority will be used, which prioritizes by object ID.

• vault – an angr.Vault object to handle storing and loading of states. If not provided, an angr.vaults.VaultShelf will be created with a temporary file.

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) –

static state_priority(state)

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) –

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) –

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_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) –

class angr.exploration_techniques.spiller_db.PickledState(**kwargs)

Bases: Base

id

priority

taken

stash

timestamp

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

metadata: MetaData = MetaData()

registry: RegistryType = <sqlalchemy.orm.decl_api.registry object>

class angr.exploration_techniques.threading.Threading(threads=8, local_stash='thread_local')

Bases: 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.

__init__(threads=8, local_stash='thread_local')

step(simgr, stash='active', error_list=None, target_stash=None, **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) –

inner_step(state, simgr, **kwargs)

successors(simgr, state, engine=None, **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) –

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) –

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_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) –

class angr.exploration_techniques.veritesting.Veritesting(**options)

Bases: 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

__init__(**options)

step_state(simgr, state, successor_func=None, **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) –

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) –

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) –

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) –

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) –

class angr.exploration_techniques.tracer.TracingMode

Bases: object

Variables:

• Strict – Strict mode, the default mode, where an exception is raised immediately if tracer’s path deviates from the provided trace.

• Permissive – Permissive mode, where tracer attempts to force the path back to the provided trace when a deviation happens. This does not always work, especially when the cause of deviation is related to input that will later be used in exploit generation. But, it might work magically sometimes.

• CatchDesync – CatchDesync mode, catch desync because of sim_procedures. It might be a sign of something interesting.

Strict = 'strict'

Permissive = 'permissive'

CatchDesync = 'catch_desync'

exception angr.exploration_techniques.tracer.TracerDesyncError(msg, deviating_addr=None, deviating_trace_idx=None)

Bases: AngrTracerError

An error class to report tracing Tracing desyncronization error

__init__(msg, deviating_addr=None, deviating_trace_idx=None)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class angr.exploration_techniques.tracer.RepHook(mnemonic)

Bases: object

Hook rep movs/stos to speed up constraint solving TODO: This should be made an exploration technique later

__init__(mnemonic)

run(state)

class angr.exploration_techniques.tracer.Tracer(trace=None, resiliency=False, keep_predecessors=1, crash_addr=None, syscall_data=None, copy_states=False, fast_forward_to_entry=True, mode='strict', aslr=True, follow_unsat=False)

Bases: 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.

• syscall_data – Data related to various syscalls recorded by tracer for replaying

• copy_states – Whether COPY_STATES should be enabled for the tracing state. It is off by default because most tracing workloads benefit greatly from not performing copying. You want to enable it if you want to see the missed states. It will be re-added for the last 2% of the trace in order to set the predecessors list correctly. If you turn this on you may want to enable the LAZY_SOLVES option.

• mode – Tracing mode.

• aslr – Whether there are aslr slides. if not, tracer uses trace address as state address.

• follow_unsat – Whether unsatisfiable states should be treated as potential successors or not.

Variables:

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

__init__(trace=None, resiliency=False, keep_predecessors=1, crash_addr=None, syscall_data=None, copy_states=False, fast_forward_to_entry=True, mode='strict', aslr=True, follow_unsat=False)

set_fd_data(fd_data)

Set concrete bytes of various fds read by the program

Parameters:

fd_data (Dict[int, bytes]) –

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

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) –

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) –

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) –

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) –

classmethod crash_windup(state, crash_addr)

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) –

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) –

class angr.exploration_techniques.driller_core.DrillerCore(trace, fuzz_bitmap=None)

Bases: 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.

__init__(trace, fuzz_bitmap=None)

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

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) –

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) –

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) –

class angr.exploration_techniques.slicecutor.Slicecutor(annotated_cfg, force_taking_exit=False, force_sat=False)

Bases: ExplorationTechnique

The Slicecutor is an exploration that executes provided code slices.

Parameters:

force_sat (bool) –

__init__(annotated_cfg, force_taking_exit=False, force_sat=False)

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.

• force_sat (bool) – If a branch specified by the slice is unsatisfiable, set this option to True if you want to force it to be satisfiable and be taken anyway.

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

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) –

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) –

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

class angr.exploration_techniques.director.BaseGoal(sort)

Bases: object

REQUIRE_CFG_STATES = False

__init__(sort)

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: BaseGoal

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

__init__(addr)

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

REQUIRE_CFG_STATES = False

class angr.exploration_techniques.director.CallFunctionGoal(function, arguments)

Bases: 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

__init__(function, arguments)

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: 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.

__init__(peek_blocks=100, peek_functions=5, goals=None, cfg_keep_states=False, goal_satisfied_callback=None, num_fallback_states=5)

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

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) –

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) –

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_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) –

class angr.exploration_techniques.oppologist.Oppologist

Bases: ExplorationTechnique

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

__init__()

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) –

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) –

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) –

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) –

class angr.exploration_techniques.loop_seer.LoopSeer(cfg=None, functions=None, loops=None, use_header=False, bound=None, bound_reached=None, discard_stash='spinning', limit_concrete_loops=True)

Bases: 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).

__init__(cfg=None, functions=None, loops=None, use_header=False, bound=None, bound_reached=None, discard_stash='spinning', limit_concrete_loops=True)

Parameters:

• cfg – Normalized CFG is required.

• functions – Function(s) containing the loop(s) to be analyzed.

• loops – Specific group of Loop(s) to be analyzed, if this is None we run the LoopFinder analysis.

• use_header – Whether to use header based trip counter to compare with the bound limit.

• bound – Limit the number of iterations a loop may be executed.

• bound_reached – If provided, should be a function that takes the LoopSeer and the succ_state. 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.

• limit_concrete_loops – If False, do not limit a loop back-edge if it is the only successor (Defaults to True to maintain the original behavior)

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

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) –

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) –

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

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) –

class angr.exploration_techniques.local_loop_seer.LocalLoopSeer(bound=None, bound_reached=None, discard_stash='spinning')

Bases: ExplorationTechnique

LocalLoopSeer monitors exploration and maintains all loop-related data without relying on a control flow graph.

__init__(bound=None, bound_reached=None, discard_stash='spinning')

Parameters:

• bound – Limit the number of iterations a loop may be executed.

• bound_reached – If provided, should be a function that takes the LoopSeer and the succ_state. 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)

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

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) –

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) –

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

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) –

class angr.exploration_techniques.stochastic.StochasticSearch(start_state, restart_prob=0.0001)

Bases: 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.

__init__(start_state, restart_prob=0.0001)

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)

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) –

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) –

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) –

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_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) –

class angr.exploration_techniques.unique.UniqueSearch(similarity_func=None, deferred_stash='deferred')

Bases: 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.

__init__(similarity_func=None, deferred_stash='deferred')

Parameters:

• similarity_func – How to calculate similarity between two states.

• deferred_stash – Where to store the deferred states.

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) –

static similarity(state_a, state_b)

The (L2) distance between the counts of the state addresses in the history of the path. :type state_a: :param state_a: The first state to compare :type state_b: :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. :type state_a: :param state_a: The first state to compare :type state_b: :param state_b: The second state to compare

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) –

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) –

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

Bases: 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 necessary stuff, hidden in the analysis instance, without passing that instance to a one-shot-styled exploration technique.

__init__(setup=None, step_state=None, step=None, successors=None, filter=None, selector=None, complete=None)

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_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) –

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) –

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) –

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) –

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) –

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.

class angr.exploration_techniques.symbion.Symbion(find=None, memory_concretize=None, register_concretize=None, timeout=0, find_stash='found')

Bases: ExplorationTechnique

The Symbion exploration technique uses the SimEngineConcrete available to step a SimState.

Parameters:

• find – address or list of addresses that we want to reach, these will be translated into breakpoints inside the concrete process using the ConcreteTarget interface provided by the user inside the SimEngineConcrete.

• memory_concretize – list of tuples (address, symbolic variable) that are going to be written in the concrete process memory.

• register_concretize – list of tuples (reg_name, symbolic variable) that are going to be written

• timeout – how long we should wait the concrete target to reach the breakpoint

__init__(find=None, memory_concretize=None, register_concretize=None, timeout=0, find_stash='found')

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) –

step_state(simgr, *args, **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) –

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) –

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) –

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) –

class angr.exploration_techniques.memory_watcher.MemoryWatcher(min_memory=512, memory_stash='lowmem')

Bases: ExplorationTechnique

Memory Watcher

Parameters:

• min_memory (int,optional) – Minimum amount of free memory in MB before stopping execution (default: 95% memory use)

• memory_stash (str, optional) – What to call the low memory stash (default: ‘lowmem’)

At each step, keep an eye on how much memory is left on the system. Stash off states to effectively stop execution if we’re below a given threshold.

__init__(min_memory=512, memory_stash='lowmem')

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

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) –

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

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) –

class angr.exploration_techniques.bucketizer.Bucketizer

Bases: ExplorationTechnique

Loop bucketization: Pick log(n) paths out of n possible paths, and stash (or drop) everything else.

__init__()

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) –

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) –

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) –

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) –

angr.exploration_techniques.suggestions.ast_weight(ast, memo=None)

class angr.exploration_techniques.suggestions.Suggestions

Bases: ExplorationTechnique

An exploration technique which analyzes failure cases and logs suggestions for how to mitigate them in future analyses.

__init__()

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) –

static report(state, event)

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) –

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) –

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_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) –

Simulation Engines

class angr.engines.UberEngine(*args, **kwargs)

Bases: SimEngineFailure, SimEngineSyscall, HooksMixin, SimEngineUnicorn, SuperFastpathMixin, TrackActionsMixin, SimInspectMixin, HeavyResilienceMixin, SootMixin, HeavyVEXMixin, TLSMixin

__init__(*args, **kwargs)

clear_cache()

get_unconstrained_simprocedure()

handle_vex_block(irsb)

irsb

lift_soot(addr=None, the_binary=None, **kwargs)

lift_vex(addr=None, state=None, clemory=None, insn_bytes=None, offset=None, arch=None, size=None, num_inst=None, traceflags=0, thumb=False, extra_stop_points=None, opt_level=None, strict_block_end=None, skip_stmts=False, collect_data_refs=False, cross_insn_opt=None, load_from_ro_regions=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.

• offset – If using insn_bytes, the number of bytes in it to skip over.

• 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)

static prepare_native_return_state(native_state)

Hook target for native function call returns.

Recovers and stores the return value from native memory and toggles the state, s.t. execution continues in the Soot engine.

static prepare_return_state(state, ret_value=None)

process(*args, skip_stmts=0, last_stmt=None, whitelist=None, **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

process_procedure(state, successors, procedure, ret_to=None, arguments=None, **kwargs)

process_successors(successors, **kwargs)

Implement this function to fill out the SimSuccessors object with the results of stepping state.

In order to implement a model where multiple mixins can potentially handle a request, a mixin may implement this method and then perform a super() call if it wants to pass on handling to the next mixin.

Keep in mind python’s method resolution order when composing multiple classes implementing this method. In short: left-to-right, depth-first, but deferring any base classes which are shared by multiple subclasses (the merge point of a diamond pattern in the inheritance graph) until the last point where they would be encountered in this depth-first search. For example, if you have classes A, B(A), C(B), D(A), E(C, D), then the method resolution order will be E, C, B, D, A.

Parameters:

• state – The state to manipulate

• successors – The successors object to fill out

• kwargs – Any extra arguments. Do not fail if you are passed unexpected arguments.

static setup_arguments(state, args)

classmethod setup_callsite(state, args, ret_addr, ret_var=None)

state

stmt_idx

successors: Optional[SimSuccessors]

static terminate_execution(statement, state, successors)

tmps

class angr.engines.UberEnginePcode(*args, **kwargs)

Bases: SimEngineFailure, SimEngineSyscall, HooksMixin, HeavyPcodeMixin

__init__(*args, **kwargs)

clear_cache()

Return type:

None

handle_pcode_block(irsb)

Execute a single IRSB.

Parameters:

irsb (IRSB) – Block to be executed.

Return type:

None

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

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 (Optional[SimState]) – A state to use as a data source.

• clemory (Optional[Clemory]) – A cle.memory.Clemory object to use as a data source.

• addr (Optional[int]) – The address at which to start the block.

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

• opt_level (Optional[int]) – Unused for P-Code lifter

• insn_bytes (Optional[bytes]) – A string of bytes to use as a data source.

• size (Optional[int]) – The maximum size of the block, in bytes.

• num_inst (Optional[int]) – The maximum number of instructions.

• traceflags (int) – Unused by P-Code lifter

• strict_block_end (Optional[bool]) – Unused by P-Code lifter

• load_from_ro_regions (bool) – Unused by P-Code lifter

• arch (Arch | None) –

• extra_stop_points (Iterable[int] | None) –

• skip_stmts (bool) –

• collect_data_refs (bool) –

• cross_insn_opt (bool | None) –

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

Temporary compatibility interface for integration with block code.

Parameters:

• addr (int | None) –

• state (SimState | None) –

• clemory (Clemory | None) –

• insn_bytes (bytes | None) –

• arch (Arch | None) –

• size (int | None) –

• num_inst (int | None) –

• traceflags (int) –

• thumb (bool) –

• extra_stop_points (Iterable[int] | None) –

• opt_level (int | None) –

• strict_block_end (bool | None) –

• skip_stmts (bool) –

• collect_data_refs (bool) –

• load_from_ro_regions (bool) –

• cross_insn_opt (bool | None) –

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

process_procedure(state, successors, procedure, ret_to=None, arguments=None, **kwargs)

process_successors(successors, **kwargs)

Implement this function to fill out the SimSuccessors object with the results of stepping state.

In order to implement a model where multiple mixins can potentially handle a request, a mixin may implement this method and then perform a super() call if it wants to pass on handling to the next mixin.

Keep in mind python’s method resolution order when composing multiple classes implementing this method. In short: left-to-right, depth-first, but deferring any base classes which are shared by multiple subclasses (the merge point of a diamond pattern in the inheritance graph) until the last point where they would be encountered in this depth-first search. For example, if you have classes A, B(A), C(B), D(A), E(C, D), then the method resolution order will be E, C, B, D, A.

Parameters:

• state – The state to manipulate

• successors – The successors object to fill out

• kwargs – Any extra arguments. Do not fail if you are passed unexpected arguments.

class angr.engines.engine.SimEngineBase(project=None, **kwargs)

Bases: object

Even more basey of a base class for SimEngine. Used as a base by mixins which want access to the project but for which having method process (contained in SimEngine) doesn’t make sense

__init__(project=None, **kwargs)

class angr.engines.engine.SimEngine(project=None, **kwargs)

Bases: SimEngineBase

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

abstract process(state, **kwargs)

The main entry point for an engine. Should take a state and return a result.

Parameters:

state – The state to proceed from

Returns:

The result. Whatever you want ;)

__init__(project=None, **kwargs)

class angr.engines.engine.TLSMixin(*args, **kwargs)

Bases: object

Mix this class into any class that defines __tls to make all of the attributes named in that list into thread-local properties.

MAGIC MAGIC MAGIC

class angr.engines.engine.TLSProperty(name)

Bases: object

__init__(name)

class angr.engines.engine.SuccessorsMixin(*args, **kwargs)

Bases: SimEngine

A mixin for SimEngine which implements process to perform common operations related to symbolic execution and dispatches to a process_successors method to fill a SimSuccessors object with the results.

__init__(*args, **kwargs)

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

process_successors(successors, **kwargs)

Implement this function to fill out the SimSuccessors object with the results of stepping state.

In order to implement a model where multiple mixins can potentially handle a request, a mixin may implement this method and then perform a super() call if it wants to pass on handling to the next mixin.

Keep in mind python’s method resolution order when composing multiple classes implementing this method. In short: left-to-right, depth-first, but deferring any base classes which are shared by multiple subclasses (the merge point of a diamond pattern in the inheritance graph) until the last point where they would be encountered in this depth-first search. For example, if you have classes A, B(A), C(B), D(A), E(C, D), then the method resolution order will be E, C, B, D, A.

Parameters:

• state – The state to manipulate

• successors – The successors object to fill out

• kwargs – Any extra arguments. Do not fail if you are passed unexpected arguments.

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/core-concepts/simulation#simsuccessors

__init__(addr, initial_state)

classmethod failure()

property is_empty

add_successor(state, target, guard, jumpkind, add_guard=True, exit_stmt_idx=None, exit_ins_addr=None, source=None)

Add a successor state of the SimRun. This procedure stores method parameters into state.scratch, does some housekeeping, and calls out to helper functions to prepare the state and categorize it into the appropriate successor lists.

Parameters:

• state (SimState) – The successor state.

• target – The target (of the jump/call/ret).

• guard – The guard expression.

• jumpkind (str) – The jumpkind (call, ret, jump, or whatnot).

• add_guard (bool) – Whether to add the guard constraint (default: True).

• exit_stmt_idx (int) – The ID of the exit statement, an integer by default. ‘default’ stands for the default exit, and None means it’s not from a statement (for example, from a SimProcedure).

• exit_ins_addr (int) – The instruction pointer of this exit, which is an integer by default.

• source (int) – The source of the jump (i.e., the address of the basic block).

class angr.engines.procedure.ProcedureMixin

Bases: object

A mixin for SimEngine which adds the process_procedure method for calling a SimProcedure and adding its results to a SimSuccessors.

process_procedure(state, successors, procedure, ret_to=None, arguments=None, **kwargs)

class angr.engines.procedure.ProcedureEngine(*args, **kwargs)

Bases: ProcedureMixin, SuccessorsMixin

A SimEngine that you may use if you only care about processing SimProcedures. Requires the procedure kwarg to be passed to process.

process_successors(successors, procedure=None, **kwargs)

Implement this function to fill out the SimSuccessors object with the results of stepping state.

In order to implement a model where multiple mixins can potentially handle a request, a mixin may implement this method and then perform a super() call if it wants to pass on handling to the next mixin.

Keep in mind python’s method resolution order when composing multiple classes implementing this method. In short: left-to-right, depth-first, but deferring any base classes which are shared by multiple subclasses (the merge point of a diamond pattern in the inheritance graph) until the last point where they would be encountered in this depth-first search. For example, if you have classes A, B(A), C(B), D(A), E(C, D), then the method resolution order will be E, C, B, D, A.

Parameters:

• state – The state to manipulate

• successors – The successors object to fill out

• kwargs – Any extra arguments. Do not fail if you are passed unexpected arguments.

__init__(*args, **kwargs)

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

process_procedure(state, successors, procedure, ret_to=None, arguments=None, **kwargs)

class angr.engines.hook.HooksMixin(*args, **kwargs)

Bases: SuccessorsMixin, ProcedureMixin

A SimEngine mixin which adds a SimSuccessors handler which will look into the project’s hooks and run the hook at the current address.

Will respond to the following parameters provided to the step stack:

• procedure: A SimProcedure instance to force-run instead of consulting the current hooks

• ret_to: An address to force-return-to at the end of the procedure

process_successors(successors, procedure=None, **kwargs)

Implement this function to fill out the SimSuccessors object with the results of stepping state.

In order to implement a model where multiple mixins can potentially handle a request, a mixin may implement this method and then perform a super() call if it wants to pass on handling to the next mixin.

Keep in mind python’s method resolution order when composing multiple classes implementing this method. In short: left-to-right, depth-first, but deferring any base classes which are shared by multiple subclasses (the merge point of a diamond pattern in the inheritance graph) until the last point where they would be encountered in this depth-first search. For example, if you have classes A, B(A), C(B), D(A), E(C, D), then the method resolution order will be E, C, B, D, A.

Parameters:

• state – The state to manipulate

• successors – The successors object to fill out

• kwargs – Any extra arguments. Do not fail if you are passed unexpected arguments.

__init__(*args, **kwargs)

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

process_procedure(state, successors, procedure, ret_to=None, arguments=None, **kwargs)

class angr.engines.syscall.SimEngineSyscall(*args, **kwargs)

Bases: SuccessorsMixin, ProcedureMixin

A SimEngine mixin which adds a successors handling step that checks if a syscall was just requested and if so handles it as a step.

process_successors(successors, **kwargs)

Implement this function to fill out the SimSuccessors object with the results of stepping state.

In order to implement a model where multiple mixins can potentially handle a request, a mixin may implement this method and then perform a super() call if it wants to pass on handling to the next mixin.

Keep in mind python’s method resolution order when composing multiple classes implementing this method. In short: left-to-right, depth-first, but deferring any base classes which are shared by multiple subclasses (the merge point of a diamond pattern in the inheritance graph) until the last point where they would be encountered in this depth-first search. For example, if you have classes A, B(A), C(B), D(A), E(C, D), then the method resolution order will be E, C, B, D, A.

Parameters:

• state – The state to manipulate

• successors – The successors object to fill out

• kwargs – Any extra arguments. Do not fail if you are passed unexpected arguments.

__init__(*args, **kwargs)

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

process_procedure(state, successors, procedure, ret_to=None, arguments=None, **kwargs)

class angr.engines.failure.SimEngineFailure(*args, **kwargs)

Bases: SuccessorsMixin, ProcedureMixin

process_successors(successors, **kwargs)

Implement this function to fill out the SimSuccessors object with the results of stepping state.

In order to implement a model where multiple mixins can potentially handle a request, a mixin may implement this method and then perform a super() call if it wants to pass on handling to the next mixin.

Keep in mind python’s method resolution order when composing multiple classes implementing this method. In short: left-to-right, depth-first, but deferring any base classes which are shared by multiple subclasses (the merge point of a diamond pattern in the inheritance graph) until the last point where they would be encountered in this depth-first search. For example, if you have classes A, B(A), C(B), D(A), E(C, D), then the method resolution order will be E, C, B, D, A.

Parameters:

• state – The state to manipulate

• successors – The successors object to fill out

• kwargs – Any extra arguments. Do not fail if you are passed unexpected arguments.

__init__(*args, **kwargs)

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

process_procedure(state, successors, procedure, ret_to=None, arguments=None, **kwargs)

class angr.engines.soot.engine.SootMixin(*args, **kwargs)

Bases: SuccessorsMixin, ProcedureMixin

Execution engine based on Soot.

lift_soot(addr=None, the_binary=None, **kwargs)

process_successors(successors, **kwargs)

Implement this function to fill out the SimSuccessors object with the results of stepping state.

In order to implement a model where multiple mixins can potentially handle a request, a mixin may implement this method and then perform a super() call if it wants to pass on handling to the next mixin.

Keep in mind python’s method resolution order when composing multiple classes implementing this method. In short: left-to-right, depth-first, but deferring any base classes which are shared by multiple subclasses (the merge point of a diamond pattern in the inheritance graph) until the last point where they would be encountered in this depth-first search. For example, if you have classes A, B(A), C(B), D(A), E(C, D), then the method resolution order will be E, C, B, D, A.

Parameters:

• state – The state to manipulate

• successors – The successors object to fill out

• kwargs – Any extra arguments. Do not fail if you are passed unexpected arguments.

get_unconstrained_simprocedure()

classmethod setup_callsite(state, args, ret_addr, ret_var=None)

static setup_arguments(state, args)

static prepare_return_state(state, ret_value=None)

static terminate_execution(statement, state, successors)

static prepare_native_return_state(native_state)

Hook target for native function call returns.

Recovers and stores the return value from native memory and toggles the state, s.t. execution continues in the Soot engine.

__init__(*args, **kwargs)

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

process_procedure(state, successors, procedure, ret_to=None, arguments=None, **kwargs)

class angr.engines.unicorn.SimEngineUnicorn(*args, **kwargs)

Bases: SuccessorsMixin

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

Responds to the following parameters in the step stack:

• step: How many basic blocks we want to execute

• extra_stop_points: A collection of addresses at which execution should halt

__init__(*args, **kwargs)

process_successors(successors, **kwargs)

Implement this function to fill out the SimSuccessors object with the results of stepping state.

In order to implement a model where multiple mixins can potentially handle a request, a mixin may implement this method and then perform a super() call if it wants to pass on handling to the next mixin.

Keep in mind python’s method resolution order when composing multiple classes implementing this method. In short: left-to-right, depth-first, but deferring any base classes which are shared by multiple subclasses (the merge point of a diamond pattern in the inheritance graph) until the last point where they would be encountered in this depth-first search. For example, if you have classes A, B(A), C(B), D(A), E(C, D), then the method resolution order will be E, C, B, D, A.

Parameters:

• state – The state to manipulate

• successors – The successors object to fill out

• kwargs – Any extra arguments. Do not fail if you are passed unexpected arguments.

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

class angr.engines.concrete.SimEngineConcrete(project)

Bases: SuccessorsMixin

Concrete execution using a concrete target provided by the user.

__init__(project)

process_successors(successors, extra_stop_points=None, memory_concretize=None, register_concretize=None, timeout=0, *args, **kwargs)

Implement this function to fill out the SimSuccessors object with the results of stepping state.

In order to implement a model where multiple mixins can potentially handle a request, a mixin may implement this method and then perform a super() call if it wants to pass on handling to the next mixin.

Keep in mind python’s method resolution order when composing multiple classes implementing this method. In short: left-to-right, depth-first, but deferring any base classes which are shared by multiple subclasses (the merge point of a diamond pattern in the inheritance graph) until the last point where they would be encountered in this depth-first search. For example, if you have classes A, B(A), C(B), D(A), E(C, D), then the method resolution order will be E, C, B, D, A.

Parameters:

• state – The state to manipulate

• successors – The successors object to fill out

• kwargs – Any extra arguments. Do not fail if you are passed unexpected arguments.

to_engine(state, extra_stop_points, memory_concretize, register_concretize, timeout)

Handle the concrete execution of the process This method takes care of: 1- Set the breakpoints on the addresses provided by the user 2- Concretize the symbolic variables and perform the write inside the concrete process 3- Continue the program execution.

Parameters:

• state – The state with which to execute

• extra_stop_points – list of a addresses where to stop the concrete execution and return to the simulated one

• memory_concretize – list of tuples (address, symbolic variable) that are going to be written in the concrete process memory.

• register_concretize – list of tuples (reg_name, symbolic variable) that are going to be written

• timeout – how long we should wait the concrete target to reach the breakpoint

Returns:

None

static check_concrete_target_methods(concrete_target)

Check if the concrete target methods return the correct type of data :return: True if the concrete target is compliant

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

class angr.engines.pcode.engine.HeavyPcodeMixin(*args, **kwargs)

Bases: SuccessorsMixin, PcodeLifterEngineMixin, PcodeEmulatorMixin

Execution engine based on P-code, Ghidra’s IR.

Responds to the following parameters to the step stack:

• irsb: The P-Code 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

• thumb: Whether the block should be force to be lifted in ARM’s THUMB mode. (FIXME)

• extra_stop_points:

  An extra set of points at which to break basic blocks

• 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.

__init__(*args, **kwargs)

process_successors(successors, irsb=None, insn_text=None, insn_bytes=None, thumb=False, size=None, num_inst=None, extra_stop_points=None, **kwargs)

Implement this function to fill out the SimSuccessors object with the results of stepping state.

In order to implement a model where multiple mixins can potentially handle a request, a mixin may implement this method and then perform a super() call if it wants to pass on handling to the next mixin.

Keep in mind python’s method resolution order when composing multiple classes implementing this method. In short: left-to-right, depth-first, but deferring any base classes which are shared by multiple subclasses (the merge point of a diamond pattern in the inheritance graph) until the last point where they would be encountered in this depth-first search. For example, if you have classes A, B(A), C(B), D(A), E(C, D), then the method resolution order will be E, C, B, D, A.

Parameters:

• state – The state to manipulate

• successors (SimSuccessors) – The successors object to fill out

• kwargs – Any extra arguments. Do not fail if you are passed unexpected arguments.

• irsb (IRSB | None) –

• insn_text (str | None) –

• insn_bytes (bytes | None) –

• thumb (bool) –

• size (int | None) –

• num_inst (int | None) –

• extra_stop_points (Iterable[int] | None) –

Return type:

None

clear_cache()

Return type:

None

handle_pcode_block(irsb)

Execute a single IRSB.

Parameters:

irsb (IRSB) – Block to be executed.

Return type:

None

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

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 (Optional[SimState]) – A state to use as a data source.

• clemory (Optional[Clemory]) – A cle.memory.Clemory object to use as a data source.

• addr (Optional[int]) – The address at which to start the block.

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

• opt_level (Optional[int]) – Unused for P-Code lifter

• insn_bytes (Optional[bytes]) – A string of bytes to use as a data source.

• size (Optional[int]) – The maximum size of the block, in bytes.

• num_inst (Optional[int]) – The maximum number of instructions.

• traceflags (int) – Unused by P-Code lifter

• strict_block_end (Optional[bool]) – Unused by P-Code lifter

• load_from_ro_regions (bool) – Unused by P-Code lifter

• arch (Arch | None) –

• extra_stop_points (Iterable[int] | None) –

• skip_stmts (bool) –

• collect_data_refs (bool) –

• cross_insn_opt (bool | None) –

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

Temporary compatibility interface for integration with block code.

Parameters:

• addr (int | None) –

• state (SimState | None) –

• clemory (Clemory | None) –

• insn_bytes (bytes | None) –

• arch (Arch | None) –

• size (int | None) –

• num_inst (int | None) –

• traceflags (int) –

• thumb (bool) –

• extra_stop_points (Iterable[int] | None) –

• opt_level (int | None) –

• strict_block_end (bool | None) –

• skip_stmts (bool) –

• collect_data_refs (bool) –

• load_from_ro_regions (bool) –

• cross_insn_opt (bool | None) –

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

class angr.engines.pcode.lifter.ExitStatement(dst, jumpkind)

Bases: object

This class exists to ease compatibility with CFGFast’s processing of exit_statements. See _scan_irsb method.

Parameters:

• dst (int | None) –

• jumpkind (str) –

__init__(dst, jumpkind)

Parameters:

• dst (int | None) –

• jumpkind (str) –

dst: Optional[int]

jumpkind: str

class angr.engines.pcode.lifter.PcodeDisassemblerBlock(addr, insns, thumb, arch)

Bases: DisassemblerBlock

Helper class to represent a block of dissassembled target architecture instructions

addr

insns

thumb

arch

__init__(addr, insns, thumb, arch)

pp()

class angr.engines.pcode.lifter.PcodeDisassemblerInsn(pcode_insn)

Bases: DisassemblerInsn

Helper class to represent a disassembled target architecture instruction

__init__(pcode_insn)

property size: int

property address: int

property mnemonic: str

property op_str: str

class angr.engines.pcode.lifter.IRSB(data, mem_addr, arch, max_inst=None, max_bytes=None, bytes_offset=0, traceflags=0, opt_level=1, num_inst=None, num_bytes=None, strict_block_end=False, skip_stmts=False, collect_data_refs=False)

Bases: object

IRSB stands for Intermediate Representation Super-Block. An IRSB in is a single-entry, multiple-exit code block.

Variables:

• arch (archinfo.Arch) – The architecture this block is lifted under

• statements (list of IRStmt) – The statements in this block

• next (IRExpr) – The expression for the default exit target of this block

• offsIP (int) – The offset of the instruction pointer in the VEX guest state

• stmts_used (int) – The number of statements in this IRSB

• jumpkind (str) – The type of this block’s default jump (call, boring, syscall, etc) as a VEX enum string

• direct_next (bool) – Whether this block ends with a direct (not indirect) jump or branch

• size (int) – The size of this block in bytes

• addr (int) – The address of this basic block, i.e. the address in the first IMark

Parameters:

• data (str | bytes | None) –

• mem_addr (int) –

• arch (Arch) –

• max_inst (int | None) –

• max_bytes (int | None) –

• bytes_offset (int) –

• traceflags (int) –

• opt_level (int) –

• num_inst (int | None) –

• num_bytes (int | None) –

• strict_block_end (bool) –

• skip_stmts (bool) –

• collect_data_refs (bool) –

MAX_EXITS = 400

MAX_DATA_REFS = 2000

__init__(data, mem_addr, arch, max_inst=None, max_bytes=None, bytes_offset=0, traceflags=0, opt_level=1, num_inst=None, num_bytes=None, strict_block_end=False, skip_stmts=False, collect_data_refs=False)

Parameters:

• data (Union[str, bytes, None]) – The bytes to lift. Can be either a string of bytes or a cffi buffer object. You may also pass None to initialize an empty IRSB.

• mem_addr (int) – The address to lift the data at.

• arch (Arch) – The architecture to lift the data as.

• max_inst (Optional[int]) – The maximum number of instructions to lift. (See note below)

• max_bytes (Optional[int]) – The maximum number of bytes to use.

• num_inst (Optional[int]) – Replaces max_inst if max_inst is None. If set to None as well, no instruction limit is used.

• num_bytes (Optional[int]) – Replaces max_bytes if max_bytes is None. If set to None as well, no byte limit is used.

• bytes_offset (int) – The offset into data to start lifting at. Note that for ARM THUMB mode, both mem_addr and bytes_offset must be odd (typically bytes_offset is set to 1).

• traceflags (int) – Unused by P-Code lifter

• opt_level (int) – Unused by P-Code lifter

• strict_block_end (bool) – Unused by P-Code lifter

• skip_stmts (bool) –

• collect_data_refs (bool) –

Return type:

None

Note

Explicitly specifying the number of instructions to lift (max_inst) may not always work exactly as expected. For example, on MIPS, it is meaningless to lift a branch or jump instruction without its delay slot. VEX attempts to Do The Right Thing by possibly decoding fewer instructions than requested. Specifically, this means that lifting a branch or jump on MIPS as a single instruction (max_inst=1) will result in an empty IRSB, and subsequent attempts to run this block will raise SimIRSBError(‘Empty IRSB passed to SimIRSB.’).

Note

If no instruction and byte limit is used, the lifter will continue lifting the block until the block ends properly or until it runs out of data to lift.

addr: int

arch: Arch

behaviors: Optional[BehaviorFactory]

data_refs: Sequence

default_exit_target: Optional

jumpkind: Optional[str]

next: Optional[int]

static empty_block(arch, addr, statements=None, nxt=None, tyenv=None, jumpkind=None, direct_next=None, size=None)

Return type:

IRSB

Parameters:

• arch (Arch) –

• addr (int) –

• statements (Sequence | None) –

• nxt (int | None) –

• jumpkind (str | None) –

• direct_next (bool | None) –

• size (int | None) –

property has_statements: bool

property exit_statements: Sequence[Tuple[int, int, ExitStatement]]

copy()

Copy by creating an empty IRSB and then filling in the leftover attributes. Copy is made as deep as possible

Return type:

IRSB

extend(extendwith)

Appends an irsb to the current irsb. The irsb that is appended is invalidated. The appended irsb’s jumpkind and default exit are used. :type extendwith: IRSB :param extendwith: The IRSB to append to this IRSB

Return type:

IRSB

Parameters:

extendwith (IRSB) –

invalidate_direct_next()

Return type:

None

pp()

Pretty-print the IRSB to stdout.

Return type:

None

property tyenv

property stmts_used: int

property offsIP: int

property direct_next: bool

property expressions

Return an iterator of all expressions contained in the IRSB.

property instructions: int

The number of instructions in this block

property instruction_addresses: Sequence[int]

Addresses of instructions in this block.

property size: int

The size of this block, in bytes

property operations

A list of all operations done by the IRSB, as libVEX enum names

property all_constants

Returns all constants in the block (including incrementing of the program counter) as pyvex.const.IRConst.

property constants

The constants (excluding updates of the program counter) in the IRSB as pyvex.const.IRConst.

property constant_jump_targets

A set of the static jump targets of the basic block.

property constant_jump_targets_and_jumpkinds

A dict of the static jump targets of the basic block to their jumpkind.

property statements: Iterable

property disassembly: PcodeDisassemblerBlock

class angr.engines.pcode.lifter.Lifter(arch, addr)

Bases: object

A lifter is a class of methods for processing a block.

Variables:

• data – The bytes to lift as either a python string of bytes or a cffi buffer object.

• bytes_offset – The offset into data to start lifting at.

• max_bytes – The maximum number of bytes to lift. If set to None, no byte limit is used.

• max_inst – The maximum number of instructions to lift. If set to None, no instruction limit is used.

• opt_level – Unused by P-Code lifter

• traceflags – Unused by P-Code lifter

• allow_arch_optimizations – Unused by P-Code lifter

• strict_block_end – Unused by P-Code lifter

• skip_stmts – Unused by P-Code lifter

Parameters:

• arch (Arch) –

• addr (int) –

REQUIRE_DATA_C = False

REQUIRE_DATA_PY = False

__init__(arch, addr)

Parameters:

• arch (Arch) –

• addr (int) –

arch: Arch

addr: int

data: Union[str, bytes, None]

bytes_offset: Optional[int]

opt_level: int

traceflags: Optional[int]

allow_arch_optimizations: Optional[bool]

strict_block_end: Optional[bool]

collect_data_refs: bool

max_inst: Optional[int]

max_bytes: Optional[int]

skip_stmts: bool

irsb: IRSB

lift()

Lifts the data using the information passed into _lift. Should be overridden in child classes.

Should set the lifted IRSB to self.irsb. If a lifter raises a LiftingException on the data, this signals that the lifter cannot lift this data and arch and the lifter is skipped. If a lifter can lift any amount of data, it should lift it and return the lifted block with a jumpkind of Ijk_NoDecode, signalling to pyvex that other lifters should be used on the undecodable data.

Return type:

None

angr.engines.pcode.lifter.lift(data, addr, arch, max_bytes=None, max_inst=None, bytes_offset=0, opt_level=1, traceflags=0, strict_block_end=True, inner=False, skip_stmts=False, collect_data_refs=False)

Lift machine code in data to a P-code IRSB.

If a lifter raises a LiftingException on the data, it is skipped. If it succeeds and returns a block with a jumpkind of Ijk_NoDecode, all of the lifters are tried on the rest of the data and if they work, their output is appended to the first block.

Parameters:

• arch (Arch) – The arch to lift the data as.

• addr (int) – The starting address of the block. Effects the IMarks.

• data (Union[str, bytes, None]) – The bytes to lift as either a python string of bytes or a cffi buffer object.

• max_bytes (Optional[int]) – The maximum number of bytes to lift. If set to None, no byte limit is used.

• max_inst (Optional[int]) – The maximum number of instructions to lift. If set to None, no instruction limit is used.

• bytes_offset (int) – The offset into data to start lifting at.

• opt_level (int) – Unused by P-Code lifter

• traceflags (int) – Unused by P-Code lifter

• strict_block_end (bool) –

• inner (bool) –

• skip_stmts (bool) –

• collect_data_refs (bool) –

Return type:

IRSB

Note

Explicitly specifying the number of instructions to lift (max_inst) may not always work exactly as expected. For example, on MIPS, it is meaningless to lift a branch or jump instruction without its delay slot. VEX attempts to Do The Right Thing by possibly decoding fewer instructions than requested. Specifically, this means that lifting a branch or jump on MIPS as a single instruction (max_inst=1) will result in an empty IRSB, and subsequent attempts to run this block will raise SimIRSBError(‘Empty IRSB passed to SimIRSB.’).

Note

If no instruction and byte limit is used, the lifter will continue lifting the block until the block ends properly or until it runs out of data to lift.

class angr.engines.pcode.lifter.PcodeBasicBlockLifter(arch)

Bases: object

Lifts basic blocks to P-code

Parameters:

arch (Arch) –

__init__(arch)

Parameters:

arch (Arch) –

context: Context

behaviors: BehaviorFactory

lift(irsb, baseaddr, data, bytes_offset=0, max_bytes=None, max_inst=None)

Return type:

None

Parameters:

• irsb (IRSB) –

• baseaddr (int) –

• data (bytes | bytearray) –

• bytes_offset (int) –

• max_bytes (int | None) –

• max_inst (int | None) –

class angr.engines.pcode.lifter.PcodeLifter(arch, addr)

Bases: Lifter

Handles calling into pypcode to lift a block

Parameters:

• arch (Arch) –

• addr (int) –

data: Union[str, bytes, None]

bytes_offset: Optional[int]

opt_level: int

traceflags: Optional[int]

allow_arch_optimizations: Optional[bool]

strict_block_end: Optional[bool]

collect_data_refs: bool

max_inst: Optional[int]

max_bytes: Optional[int]

skip_stmts: bool

irsb: IRSB

arch: Arch

addr: int

REQUIRE_DATA_C = False

REQUIRE_DATA_PY = False

__init__(arch, addr)

Parameters:

• arch (Arch) –

• addr (int) –

lift()

Lifts the data using the information passed into _lift. Should be overridden in child classes.

Should set the lifted IRSB to self.irsb. If a lifter raises a LiftingException on the data, this signals that the lifter cannot lift this data and arch and the lifter is skipped. If a lifter can lift any amount of data, it should lift it and return the lifted block with a jumpkind of Ijk_NoDecode, signalling to pyvex that other lifters should be used on the undecodable data.

Return type:

None

class angr.engines.pcode.lifter.PcodeLifterEngineMixin(project, use_cache=None, cache_size=50000, default_opt_level=1, selfmodifying_code=None, single_step=False, default_strict_block_end=False, **kwargs)

Bases: SimEngineBase

Lifter mixin to lift from machine code to P-Code.

Parameters:

• use_cache (bool | None) –

• cache_size (int) –

• default_opt_level (int) –

• selfmodifying_code (bool | None) –

• single_step (bool) –

• default_strict_block_end (bool) –

__init__(project, use_cache=None, cache_size=50000, default_opt_level=1, selfmodifying_code=None, single_step=False, default_strict_block_end=False, **kwargs)

Parameters:

• use_cache (bool | None) –

• cache_size (int) –

• default_opt_level (int) –

• selfmodifying_code (bool | None) –

• single_step (bool) –

• default_strict_block_end (bool) –

clear_cache()

Return type:

None

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

Temporary compatibility interface for integration with block code.

Parameters:

• addr (int | None) –

• state (SimState | None) –

• clemory (Clemory | None) –

• insn_bytes (bytes | None) –

• arch (Arch | None) –

• size (int | None) –

• num_inst (int | None) –

• traceflags (int) –

• thumb (bool) –

• extra_stop_points (Iterable[int] | None) –

• opt_level (int | None) –

• strict_block_end (bool | None) –

• skip_stmts (bool) –

• collect_data_refs (bool) –

• load_from_ro_regions (bool) –

• cross_insn_opt (bool | None) –

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

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 (Optional[SimState]) – A state to use as a data source.

• clemory (Optional[Clemory]) – A cle.memory.Clemory object to use as a data source.

• addr (Optional[int]) – The address at which to start the block.

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

• opt_level (Optional[int]) – Unused for P-Code lifter

• insn_bytes (Optional[bytes]) – A string of bytes to use as a data source.

• size (Optional[int]) – The maximum size of the block, in bytes.

• num_inst (Optional[int]) – The maximum number of instructions.

• traceflags (int) – Unused by P-Code lifter

• strict_block_end (Optional[bool]) – Unused by P-Code lifter

• load_from_ro_regions (bool) – Unused by P-Code lifter

• arch (Arch | None) –

• extra_stop_points (Iterable[int] | None) –

• skip_stmts (bool) –

• collect_data_refs (bool) –

• cross_insn_opt (bool | None) –

class angr.engines.pcode.emulate.PcodeEmulatorMixin(*args, **kwargs)

Bases: SimEngineBase

Mixin for p-code execution.

__init__(*args, **kwargs)

handle_pcode_block(irsb)

Execute a single IRSB.

Parameters:

irsb (IRSB) – Block to be executed.

Return type:

None

angr.engines.pcode.behavior.make_bv_sizes_equal(bv1, bv2)

Makes two BVs equal in length through sign extension.

Return type:

Tuple[BV, BV]

Parameters:

• bv1 (BV) –

• bv2 (BV) –

class angr.engines.pcode.behavior.OpBehavior(opcode, is_unary, is_special=False)

Bases: object

Base class for all operation behaviors.

Parameters:

• opcode (int) –

• is_unary (bool) –

• is_special (bool) –

__init__(opcode, is_unary, is_special=False)

Parameters:

• opcode (int) –

• is_unary (bool) –

• is_special (bool) –

Return type:

None

opcode: int

is_unary: bool

is_special: bool

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

class angr.engines.pcode.behavior.OpBehaviorCopy

Bases: OpBehavior

Behavior for the COPY operation.

__init__()

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorEqual

Bases: OpBehavior

Behavior for the INT_EQUAL operation.

__init__()

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorNotEqual

Bases: OpBehavior

Behavior for the INT_NOTEQUAL operation.

__init__()

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorIntSless

Bases: OpBehavior

Behavior for the INT_SLESS operation.

__init__()

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorIntSlessEqual

Bases: OpBehavior

Behavior for the INT_SLESSEQUAL operation.

__init__()

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorIntLess

Bases: OpBehavior

Behavior for the INT_LESS operation.

__init__()

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorIntLessEqual

Bases: OpBehavior

Behavior for the INT_LESSEQUAL operation.

__init__()

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorIntZext

Bases: OpBehavior

Behavior for the INT_ZEXT operation.

__init__()

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorIntSext

Bases: OpBehavior

Behavior for the INT_SEXT operation.

__init__()

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorIntAdd

Bases: OpBehavior

Behavior for the INT_ADD operation.

__init__()

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorIntSub

Bases: OpBehavior

Behavior for the INT_SUB operation.

__init__()

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorIntCarry

Bases: OpBehavior

Behavior for the INT_CARRY operation.

__init__()

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorIntScarry

Bases: OpBehavior

Behavior for the INT_SCARRY operation.

__init__()

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorIntSborrow

Bases: OpBehavior

Behavior for the INT_SBORROW operation.

__init__()

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorInt2Comp

Bases: OpBehavior

Behavior for the INT_2COMP operation.

__init__()

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorIntNegate

Bases: OpBehavior

Behavior for the INT_NEGATE operation.

__init__()

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorIntXor

Bases: OpBehavior

Behavior for the INT_XOR operation.

__init__()

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorIntAnd

Bases: OpBehavior

Behavior for the INT_AND operation.

__init__()

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorIntOr

Bases: OpBehavior

Behavior for the INT_OR operation.

__init__()

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorIntLeft

Bases: OpBehavior

Behavior for the INT_LEFT operation.

__init__()

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorIntRight

Bases: OpBehavior

Behavior for the INT_RIGHT operation.

__init__()

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorIntSright

Bases: OpBehavior

Behavior for the INT_SRIGHT operation.

__init__()

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorIntMult

Bases: OpBehavior

Behavior for the INT_MULT operation.

__init__()

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorIntDiv

Bases: OpBehavior

Behavior for the INT_DIV operation.

__init__()

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorIntSdiv

Bases: OpBehavior

Behavior for the INT_SDIV operation.

__init__()

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorIntRem

Bases: OpBehavior

Behavior for the INT_REM operation.

__init__()

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorIntSrem

Bases: OpBehavior

Behavior for the INT_SREM operation.

__init__()

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorBoolNegate

Bases: OpBehavior

Behavior for the BOOL_NEGATE operation.

__init__()

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorBoolXor

Bases: OpBehavior

Behavior for the BOOL_XOR operation.

__init__()

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorBoolAnd

Bases: OpBehavior

Behavior for the BOOL_AND operation.

__init__()

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorBoolOr

Bases: OpBehavior

Behavior for the BOOL_OR operation.

__init__()

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorFloatEqual

Bases: OpBehavior

Behavior for the FLOAT_EQUAL operation.

__init__()

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorFloatNotEqual

Bases: OpBehavior

Behavior for the FLOAT_NOTEQUAL operation.

__init__()

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorFloatLess

Bases: OpBehavior

Behavior for the FLOAT_LESS operation.

__init__()

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorFloatLessEqual

Bases: OpBehavior

Behavior for the FLOAT_LESSEQUAL operation.

__init__()

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorFloatNan

Bases: OpBehavior

Behavior for the FLOAT_NAN operation.

__init__()

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorFloatAdd

Bases: OpBehavior

Behavior for the FLOAT_ADD operation.

__init__()

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorFloatDiv

Bases: OpBehavior

Behavior for the FLOAT_DIV operation.

__init__()

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorFloatMult

Bases: OpBehavior

Behavior for the FLOAT_MULT operation.

__init__()

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorFloatSub

Bases: OpBehavior

Behavior for the FLOAT_SUB operation.

__init__()

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorFloatNeg

Bases: OpBehavior

Behavior for the FLOAT_NEG operation.

__init__()

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorFloatAbs

Bases: OpBehavior

Behavior for the FLOAT_ABS operation.

__init__()

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorFloatSqrt

Bases: OpBehavior

Behavior for the FLOAT_SQRT operation.

__init__()

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorFloatInt2Float

Bases: OpBehavior

Behavior for the FLOAT_INT2FLOAT operation.

__init__()

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorFloatFloat2Float

Bases: OpBehavior

Behavior for the FLOAT_FLOAT2FLOAT operation.

__init__()

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorFloatTrunc

Bases: OpBehavior

Behavior for the FLOAT_TRUNC operation.

__init__()

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorFloatCeil

Bases: OpBehavior

Behavior for the FLOAT_CEIL operation.

__init__()

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorFloatFloor

Bases: OpBehavior

Behavior for the FLOAT_FLOOR operation.

__init__()

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorFloatRound

Bases: OpBehavior

Behavior for the FLOAT_ROUND operation.

__init__()

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorPiece

Bases: OpBehavior

Behavior for the PIECE operation.

__init__()

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorSubpiece

Bases: OpBehavior

Behavior for the SUBPIECE operation.

__init__()

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.OpBehaviorPopcount

Bases: OpBehavior

Behavior for the POPCOUNT operation.

__init__()

evaluate_unary(size_out, size_in, in1)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

opcode: int

is_unary: bool

is_special: bool

classmethod booleanize(in1)

Reduce input BV to a single bit of truth: out <- 1 if (in1 != 0) else 0.

Return type:

BV

Parameters:

in1 (BV) –

evaluate_binary(size_out, size_in, in1, in2)

Return type:

BV

Parameters:

• size_out (int) –

• size_in (int) –

• in1 (BV) –

• in2 (BV) –

static generic_compare(args, comparison)

Return type:

BV

Parameters:

• args (Iterable[BV]) –

• comparison (Callable[[BV, BV], BV]) –

class angr.engines.pcode.behavior.BehaviorFactory

Bases: object

Returns the behavior object for a given opcode.

__init__()

get_behavior_for_opcode(opcode)

Return type:

OpBehavior

Parameters:

opcode (int) –

class angr.engines.pcode.cc.SimCCM68k(arch)

Bases: SimCC

Default CC for M68k

Parameters:

arch (Arch) –

ARG_REGS: List[str] = []

FP_ARG_REGS: List[str] = []

STACKARG_SP_DIFF = 4

RETURN_VAL: SimFunctionArgument = <d0>

RETURN_ADDR: SimFunctionArgument = [0x0]

ARCH = None

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

CALLER_SAVED_REGS: List[str] = []

FP_RETURN_VAL: Optional[SimFunctionArgument] = None

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

STACKARG_SP_BUFF = 0

STACK_ALIGNMENT = 1

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

next_arg(session, arg_type)

Parameters:

• session (ArgSession) –

• arg_type (SimType) –

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, stack_base=None, perspective_returned=False)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.engines.pcode.cc.SimCCRISCV(arch)

Bases: SimCC

Default CC for RISCV

Parameters:

arch (Arch) –

ARG_REGS: List[str] = ['a0', 'a1', 'a2', 'a3', 'a4', 'a5', 'a6', 'a7']

RETURN_ADDR: SimFunctionArgument = <ra>

RETURN_VAL: SimFunctionArgument = <a0>

ARCH = None

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

CALLER_SAVED_REGS: List[str] = []

FP_ARG_REGS: List[str] = []

FP_RETURN_VAL: Optional[SimFunctionArgument] = None

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

STACKARG_SP_BUFF = 0

STACKARG_SP_DIFF = 0

STACK_ALIGNMENT = 1

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

next_arg(session, arg_type)

Parameters:

• session (ArgSession) –

• arg_type (SimType) –

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, stack_base=None, perspective_returned=False)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.engines.pcode.cc.SimCCSPARC(arch)

Bases: SimCC

Default CC for SPARC

Parameters:

arch (Arch) –

ARG_REGS: List[str] = ['o0', 'o1']

RETURN_VAL: SimFunctionArgument = <o0>

RETURN_ADDR: SimFunctionArgument = <o7>

ARCH = None

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

CALLER_SAVED_REGS: List[str] = []

FP_ARG_REGS: List[str] = []

FP_RETURN_VAL: Optional[SimFunctionArgument] = None

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

STACKARG_SP_BUFF = 0

STACKARG_SP_DIFF = 0

STACK_ALIGNMENT = 1

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

next_arg(session, arg_type)

Parameters:

• session (ArgSession) –

• arg_type (SimType) –

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, stack_base=None, perspective_returned=False)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.engines.pcode.cc.SimCCSH4(arch)

Bases: SimCC

Default CC for SH4

Parameters:

arch (Arch) –

ARG_REGS: List[str] = ['r4', 'r5']

RETURN_VAL: SimFunctionArgument = <r0>

RETURN_ADDR: SimFunctionArgument = <pr>

ARCH = None

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

CALLER_SAVED_REGS: List[str] = []

FP_ARG_REGS: List[str] = []

FP_RETURN_VAL: Optional[SimFunctionArgument] = None

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

STACKARG_SP_BUFF = 0

STACKARG_SP_DIFF = 0

STACK_ALIGNMENT = 1

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

next_arg(session, arg_type)

Parameters:

• session (ArgSession) –

• arg_type (SimType) –

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, stack_base=None, perspective_returned=False)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.engines.pcode.cc.SimCCPARISC(arch)

Bases: SimCC

Default CC for PARISC

Parameters:

arch (Arch) –

ARG_REGS: List[str] = ['r26', 'r25']

RETURN_VAL: SimFunctionArgument = <r28>

RETURN_ADDR: SimFunctionArgument = <rp>

ARCH = None

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

CALLER_SAVED_REGS: List[str] = []

FP_ARG_REGS: List[str] = []

FP_RETURN_VAL: Optional[SimFunctionArgument] = None

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

STACKARG_SP_BUFF = 0

STACKARG_SP_DIFF = 0

STACK_ALIGNMENT = 1

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

next_arg(session, arg_type)

Parameters:

• session (ArgSession) –

• arg_type (SimType) –

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, stack_base=None, perspective_returned=False)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.engines.pcode.cc.SimCCPowerPC(arch)

Bases: SimCC

Default CC for PowerPC

Parameters:

arch (Arch) –

ARG_REGS: List[str] = ['r3', 'r4', 'r5', 'r6', 'r7', 'r8', 'r9', 'r10']

FP_ARG_REGS: List[str] = []

STACKARG_SP_BUFF = 8

RETURN_ADDR: SimFunctionArgument = <lr>

RETURN_VAL: SimFunctionArgument = <r3>

ARCH = None

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

CALLER_SAVED_REGS: List[str] = []

FP_RETURN_VAL: Optional[SimFunctionArgument] = None

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

STACKARG_SP_DIFF = 0

STACK_ALIGNMENT = 1

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

next_arg(session, arg_type)

Parameters:

• session (ArgSession) –

• arg_type (SimType) –

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, stack_base=None, perspective_returned=False)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

angr.engines.pcode.cc.register_pcode_arch_default_cc(arch)

Parameters:

arch (ArchPcode) –

Simulation Logging

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

Bases: SimEvent

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

TMP = 'tmp'

REG = 'reg'

MEM = 'mem'

__init__(state, region_type)

Initializes the SimAction.

Parameters:

state – the state that’s the SimAction is taking place in.

property all_objects

property is_symbolic

property tmp_deps

property 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: SimAction

An Exit action represents a (possibly conditional) jump.

CONDITIONAL = 'conditional'

DEFAULT = 'default'

__init__(state, target, condition=None, exit_type=None)

Initializes the SimAction.

Parameters:

state – the state that’s the SimAction is taking place in.

property all_objects

property is_symbolic

MEM = 'mem'

REG = 'reg'

TMP = 'tmp'

copy()

downsize()

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

property reg_deps

property tmp_deps

class angr.state_plugins.sim_action.SimActionConstraint(state, constraint, condition=None)

Bases: SimAction

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

__init__(state, constraint, condition=None)

Initializes the SimAction.

Parameters:

state – the state that’s the SimAction is taking place in.

property all_objects

property is_symbolic

MEM = 'mem'

REG = 'reg'

TMP = 'tmp'

copy()

downsize()

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

property reg_deps

property tmp_deps

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

Bases: SimAction

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

__init__(state, op, exprs, result)

Initializes the SimAction.

Parameters:

state – the state that’s the SimAction is taking place in.

property all_objects

property is_symbolic

MEM = 'mem'

REG = 'reg'

TMP = 'tmp'

copy()

downsize()

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

property reg_deps

property tmp_deps

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: SimAction

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

READ = 'read'

WRITE = 'write'

OPERATE = 'operate'

__init__(state, region_type, action, tmp=None, addr=None, size=None, data=None, condition=None, fallback=None, fd=None)

Initializes the SimAction.

Parameters:

state – the state that’s the SimAction is taking place in.

downsize()

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

property all_objects

property is_symbolic

property tmp_deps

MEM = 'mem'

REG = 'reg'

TMP = 'tmp'

copy()

property reg_deps

property storage

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, deps=None, state=None)

Bases: object

A SimActionObject tracks an AST and its dependencies.

__init__(ast, reg_deps=None, tmp_deps=None, deps=None, state=None)

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

A SimEvent is a log entry for some notable event during symbolic execution. It logs the location it was generated (ins_addr, bbl_addr, stmt_idx, and sim_procedure) as well as arbitrary tags (objects).

You may also be interested in SimAction, which is a specialization of SimEvent for CPU events.

__init__(state, event_type, **kwargs)

angr.state_plugins.sim_event.resource_event(state, exception)

Procedures

class angr.sim_procedure.SimProcedure(project=None, cc=None, prototype=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/extending-angr/simprocedures

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

• library_name – The name of the library from which the function we’re emulating comes

• 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

The following class variables should be set if necessary when implementing a new SimProcedure:

Variables:

• NO_RET – Set this to true if control flow will never return from this function

• DYNAMIC_RET – Set this to true if whether the control flow returns from this function or not depends on the context (e.g., libc’s error() call). Must implement dynamic_returns() method.

• ADDS_EXITS – Set this to true if you do any control flow other than returning

• IS_FUNCTION – Does this procedure simulate a function? True by default

• ARGS_MISMATCH – Does this procedure have a different list of arguments than what is provided in the function specification? This may happen when we manually extract arguments in the run() method of a SimProcedure. False by default.

• local_vars – If you use self.call(), set this to a list of all the local variable names in your class. They will be restored on return.

The following instance variables are available when working with simprocedures from the inside or the outside:

Variables:

• project – The associated angr project

• arch – The associated architecture

• addr – The linear address at which the procedure is executing

• cc – The calling convention in use for engaging with the ABI

• canonical – The canonical version of this SimProcedure. Procedures are deepcopied for many reasons, including to be able to store state related to a specific run and to be able to hook continuations.

• kwargs – Any extra keyword arguments used to construct the procedure; will be passed to run

• display_name – See the eponymous parameter

• library_name – See the eponymous parameter

• abi – If this is a syscall simprocedure, which ABI are we using to map the syscall numbers?

• symbolic_return – See the eponymous parameter

• syscall_number – If this procedure is a syscall, the number will be populated here.

• returns – See eponymous parameter and NO_RET cvar

• is_syscall – See eponymous parameter

• is_function – See eponymous parameter and cvar

• is_stub – See eponymous parameter

• is_continuation – Whether this procedure is the original or a continuation resulting from self.call()

• continuations – A mapping from name to each known continuation

• run_func – The name of the function implementing the procedure. “run” by default, but different in continuations.

• num_args – The number of arguments to the procedure. If not provided in the parameter, extracted from the definition of self.run

The following instance variables are only used in a copy of the procedure that is actually executing on a state:

Variables:

• state – The SimState we should be mutating to perform the procedure

• successors – The SimSuccessors associated with the current step

• arguments – The function arguments, deserialized from the state

• arg_session – The ArgSession that was used to parse arguments out of the state, in case you need it for varargs

• use_state_arguments – Whether we’re using arguments extracted from the state or manually provided

• ret_to – The current return address

• ret_expr – The computed return value

• call_ret_expr – The return value from having used self.call()

• inhibit_autoret – Whether we should avoid automatically adding an exit for returning once the run function ends

• arg_session – The ArgSession object that was used to extract the runtime argument values. Useful for if you want to extract variadic args.

__init__(project=None, cc=None, prototype=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)

state: SimState

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

DYNAMIC_RET = False

ADDS_EXITS = False

IS_FUNCTION = True

ARGS_MISMATCH = False

ALT_NAMES = None

local_vars: Tuple[str, ...] = ()

run(*args, **kwargs)

Implement the actual procedure here!

static_exits(blocks, **kwargs)

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 dicts. Each dict should contain the following entries: ‘address’, ‘jumpkind’, and ‘namehint’.

Return type:

list

dynamic_returns(blocks, **kwargs)

Determines if a call to this function returns or not by performing static analysis and heuristics.

Parameters:

blocks – Blocks that are executed before reaching this SimProcedure.

Return type:

bool

Returns:

True if the call returns, False otherwise.

property should_add_successors

set_args(args)

va_arg(ty, index=None)

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, prototype=None, jumpkind='Ijk_Call')

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.

• prototype – Optional: The prototype to use for the call. Will default to all-ints.

jump(addr, jumpkind='Ijk_Boring')

Add an exit representing jumping to an address.

exit(exit_code)

Add an exit representing terminating the program.

ty_ptr(ty)

property is_java

property argument_types

property return_type

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

Bases: object

Describes a format string.

SCANF_DELIMITERS = [b'\t', b'\n', b'\x0b', b'\r', b' ']

__init__(parser, components)

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

property state

replace(va_arg)

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

Parameters:

va_arg – A function which takes a type and returns the next argument of that type

Returns:

The result formatted string

interpret(va_arg, 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:

• va_arg – A function which, given a type, returns the next argument of that type

• 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, pad_chr, size, signed)

Bases: object

Describes a format specifier within a format string.

__init__(string, length_spec, pad_chr, size, signed)

string

size

signed

length_spec

pad_chr

property spec_type

class angr.procedures.stubs.format_parser.FormatParser(project=None, cc=None, prototype=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: SimProcedure

For SimProcedures relying on printf-style format strings.

Parameters:

• project (Project) –

• cc (SimCC) –

• prototype (SimTypeFunction) –

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': unsigned int*, b'o': unsigned int, b'p': unsigned int*, 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': (short, unsigned short), b'hh': (char, char), b'j': (long long, unsigned long long), b'l': (long, unsigned long), b'll': (long long, unsigned long long), b't': (long, long), b'z': (size_t, size_t)}

other_types = {('string',): <function FormatParser.<lambda>>}

flags = ['#', '0', '\\-', ' ', '\\+', "\\'", 'I']

extract_components(fmt)

Extract the actual formats from the format string fmt.

Parameters:

fmt (List) – A list of format chars.

Return type:

List

Returns:

a FormatString object

ADDS_EXITS = False

ALT_NAMES = None

DYNAMIC_RET = False

IS_FUNCTION = True

NO_RET = False

__init__(project=None, cc=None, prototype=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)

property argument_types

call(addr, args, continue_at, cc=None, prototype=None, jumpkind='Ijk_Call')

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.

• prototype – Optional: The prototype to use for the call. Will default to all-ints.

dynamic_returns(blocks, **kwargs)

Determines if a call to this function returns or not by performing static analysis and heuristics.

Parameters:

blocks – Blocks that are executed before reaching this SimProcedure.

Return type:

bool

Returns:

True if the call returns, False otherwise.

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.

exit(exit_code)

Add an exit representing terminating the program.

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

property is_java

jump(addr, jumpkind='Ijk_Boring')

Add an exit representing jumping to an address.

local_vars: Tuple[str, ...] = ()

make_continuation(name)

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.

property return_type

run(*args, **kwargs)

Implement the actual procedure here!

set_args(args)

property should_add_successors

static_exits(blocks, **kwargs)

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 dicts. Each dict should contain the following entries: ‘address’, ‘jumpkind’, and ‘namehint’.

Return type:

list

ty_ptr(ty)

va_arg(ty, index=None)

state: SimState

project: angr.Project

arch: archinfo.arch.Arch

cc: angr.SimCC

prototype: angr.sim_type.SimTypeFunction

arg_session: Union[None, ArgSession, int]

class angr.procedures.stubs.format_parser.ScanfFormatParser(project=None, cc=None, prototype=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: FormatParser

For SimProcedures relying on scanf-style format strings.

basic_spec = {b'A': float, b'E': float, b'F': float, b'G': float, b'X': unsigned int, b'a': float, b'c': char, b'd': int, b'e': float, b'f': float, b'g': float, b'i': int, b'n': unsigned int*, b'o': unsigned int, b'p': unsigned int*, b's': char*, b'u': unsigned int, b'x': unsigned int}

float_spec = [b'e', b'E', b'f', b'F', b'g', b'G', b'a', b'A']

float_len_mod = {b'l': <class 'angr.sim_type.SimTypeDouble'>, b'll': <class 'angr.sim_type.SimTypeDouble'>}

ADDS_EXITS = False

ALT_NAMES = None

ARGS_MISMATCH = True

DYNAMIC_RET = False

IS_FUNCTION = True

NO_RET = False

__init__(project=None, cc=None, prototype=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)

property argument_types

call(addr, args, continue_at, cc=None, prototype=None, jumpkind='Ijk_Call')

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.

• prototype – Optional: The prototype to use for the call. Will default to all-ints.

dynamic_returns(blocks, **kwargs)

Determines if a call to this function returns or not by performing static analysis and heuristics.

Parameters:

blocks – Blocks that are executed before reaching this SimProcedure.

Return type:

bool

Returns:

True if the call returns, False otherwise.

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.

exit(exit_code)

Add an exit representing terminating the program.

extract_components(fmt)

Extract the actual formats from the format string fmt.

Parameters:

fmt (List) – A list of format chars.

Return type:

List

Returns:

a FormatString object

flags = ['#', '0', '\\-', ' ', '\\+', "\\'", 'I']

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

int_len_mod = {b'h': (short, unsigned short), b'hh': (char, char), b'j': (long long, unsigned long long), b'l': (long, unsigned long), b'll': (long long, unsigned long long), b't': (long, long), b'z': (size_t, size_t)}

int_sign = {'signed': [b'd', b'i'], 'unsigned': [b'o', b'u', b'x', b'X']}

property is_java

jump(addr, jumpkind='Ijk_Boring')

Add an exit representing jumping to an address.

local_vars: Tuple[str, ...] = ()

make_continuation(name)

other_types = {('string',): <function FormatParser.<lambda>>}

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.

property return_type

run(*args, **kwargs)

Implement the actual procedure here!

set_args(args)

property should_add_successors

static_exits(blocks, **kwargs)

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 dicts. Each dict should contain the following entries: ‘address’, ‘jumpkind’, and ‘namehint’.

Return type:

list

ty_ptr(ty)

va_arg(ty, index=None)

state: SimState

project: angr.Project

arch: archinfo.arch.Arch

cc: angr.SimCC

prototype: angr.sim_type.SimTypeFunction

arg_session: Union[None, ArgSession, int]

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.

__init__()

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

property 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.

get_prototype(name, arch=None)

Get a prototype of the given function name, optionally specialize the prototype to a given architecture.

Parameters:

• name (str) – Name of the function.

• arch – The architecture to specialize to.

Return type:

Optional[SimTypeFunction]

Returns:

Prototype of the function, or None if the prototype does not exist.

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.SimCppLibrary

Bases: SimLibrary

SimCppLibrary is a specialized version of SimLibrary that will demangle C++ function names before looking for an implementation or prototype for it.

get(name, arch)

Get an implementation of the given function specialized for the given arch, or a stub procedure if none exists. Demangle the function name if it is a mangled C++ name.

Parameters:

• name (str) – 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. Demangle the function name if it is a mangled C++ name.

Parameters:

• name (str) – 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.

get_prototype(name, arch=None)

Get a prototype of the given function name, optionally specialize the prototype to a given architecture. The function name will be demangled first.

Parameters:

• name (str) – Name of the function.

• arch – The architecture to specialize to.

Return type:

Optional[SimTypeFunction]

Returns:

Prototype of the function, or None if the prototype does not exist.

has_metadata(name)

Check if a function has either an implementation or any metadata associated with it. Demangle the function name if it is a mangled C++ name.

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. Demangle the function name if it is a mangled C++ name.

Parameters:

name (str) – A mangled function name.

Returns:

bool

has_prototype(func_name)

Check if a function has a prototype associated with it. Demangle the function name if it is a mangled C++ name.

Parameters:

name (str) – A mangled function name.

Returns:

bool

__init__()

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_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

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

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

property name

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

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

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_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_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

update(other)

Augment this SimLibrary with the information from another SimLibrary

Parameters:

other – The other SimLibrary

class angr.procedures.definitions.SimSyscallLibrary

Bases: 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 inherently 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.

__init__()

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

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

set_prototype(abi, name, proto)

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

Parameters:

• abi (str) – ABI of the syscall.

• name (str) – The name of the syscall as a string

• proto (SimTypeFunction) – The prototype of the syscall as a SimTypeFunction

Return type:

None

set_prototypes(abi, protos)

Set the prototypes of many syscalls.

Parameters:

• abi (str) – ABI of the syscalls.

• protos (Dict[str, SimTypeFunction]) – Dictionary mapping syscall names to SimTypeFunction objects

Return type:

None

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

get_prototype(abi, name, arch=None)

Get a prototype of the given syscall name and its ABI, optionally specialize the prototype to a given architecture.

Parameters:

• abi (str) – ABI of the prototype to get.

• name (str) – Name of the syscall.

• arch – The architecture to specialize to.

Return type:

Optional[SimTypeFunction]

Returns:

Prototype of the syscall, or None if the prototype does not exist.

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

has_prototype(abi, name)

Check if a function has a prototype associated with it. Demangle the function name if it is a mangled C++ name.

Parameters:

• abi (str) – Name of the ABI.

• name (str) – The syscall name.

Return type:

bool

Returns:

bool

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_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

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

property name

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

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

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_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_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

angr.procedures.definitions.load_win32api_definitions()

angr.procedures.definitions.load_all_definitions()

Calling Conventions and Types

class angr.calling_conventions.PointerWrapper(value, buffer=False)

Bases: object

__init__(value, buffer=False)

class angr.calling_conventions.AllocHelper(ptrsize)

Bases: object

__init__(ptrsize)

alloc(size)

dump(val, state, loc=None)

translate(val, base)

apply(state, base)

size()

classmethod calc_size(val, arch)

classmethod stack_loc(val, arch, offset=0)

angr.calling_conventions.refine_locs_with_struct_type(arch, locs, arg_type, offset=0, treat_bot_as_int=True)

Parameters:

• arch (Arch) –

• locs (List) –

• arg_type (SimType) –

• offset (int) –

class angr.calling_conventions.SerializableIterator

Bases: object

getstate()

setstate(state)

class angr.calling_conventions.SerializableListIterator(lst)

Bases: SerializableIterator

__init__(lst)

getstate()

setstate(state)

class angr.calling_conventions.SerializableCounter(start, stride, mapping=<function SerializableCounter.<lambda>>)

Bases: SerializableIterator

__init__(start, stride, mapping=<function SerializableCounter.<lambda>>)

getstate()

setstate(state)

class angr.calling_conventions.SimFunctionArgument(size, is_fp=False)

Bases: object

Represent a generic function argument.

Variables:

• size (int) – The size of the argument, in number of bytes.

• is_fp (bool) – Whether loads from this location should return a floating point bitvector

__init__(size, is_fp=False)

check_value_set(value, arch)

check_value_get(value)

set_value(state, value, **kwargs)

get_value(state, **kwargs)

refine(size, arch=None, offset=None, is_fp=None)

get_footprint()

Return a list of SimRegArg and SimStackArgs that are the base components used for this location

class angr.calling_conventions.SimRegArg(reg_name, size, reg_offset=0, is_fp=False, clear_entire_reg=False)

Bases: SimFunctionArgument

Represents a function argument that has been passed in a register.

Variables:

• reg_name (string) – The name of the represented register.

• size (int) – The size of the data to store, in number of bytes.

• reg_offset – The offset into the register to start storing data.

• clear_entire_reg – Whether a store to this register should zero the unused parts of the register.

• is_fp (bool) – Whether loads from this location should return a floating point bitvector

Parameters:

• reg_name (str) –

• size (int) –

__init__(reg_name, size, reg_offset=0, is_fp=False, clear_entire_reg=False)

Parameters:

• reg_name (str) –

• size (int) –

get_footprint()

Return a list of SimRegArg and SimStackArgs that are the base components used for this location

check_offset(arch)

set_value(state, value, **kwargs)

get_value(state, **kwargs)

refine(size, arch=None, offset=None, is_fp=None)

sse_extend()

check_value_get(value)

check_value_set(value, arch)

class angr.calling_conventions.SimStackArg(stack_offset, size, is_fp=False)

Bases: SimFunctionArgument

Represents a function argument that has been passed on the stack.

Variables:

• stack_offset (int) – The position of the argument relative to the stack pointer after the function prelude.

• size (int) – The size of the argument, in number of bytes.

• is_fp (bool) – Whether loads from this location should return a floating point bitvector

__init__(stack_offset, size, is_fp=False)

get_footprint()

Return a list of SimRegArg and SimStackArgs that are the base components used for this location

set_value(state, value, stack_base=None, **kwargs)

get_value(state, stack_base=None, **kwargs)

refine(size, arch=None, offset=None, is_fp=None)

check_value_get(value)

check_value_set(value, arch)

class angr.calling_conventions.SimComboArg(locations, is_fp=False)

Bases: SimFunctionArgument

An argument which spans multiple storage locations. Locations should be given least-significant first.

__init__(locations, is_fp=False)

get_footprint()

Return a list of SimRegArg and SimStackArgs that are the base components used for this location

set_value(state, value, **kwargs)

get_value(state, **kwargs)

check_value_get(value)

check_value_set(value, arch)

refine(size, arch=None, offset=None, is_fp=None)

class angr.calling_conventions.SimStructArg(struct, locs)

Bases: SimFunctionArgument

An argument which de/serializes a struct from a list of storage locations

Variables:

• struct – The simtype describing the structure

• locs – The storage locations to use

Parameters:

• struct (SimStruct) –

• locs (Dict[str, SimFunctionArgument]) –

__init__(struct, locs)

Parameters:

• struct (SimStruct) –

• locs (Dict[str, SimFunctionArgument]) –

get_footprint()

Return a list of SimRegArg and SimStackArgs that are the base components used for this location

get_value(state, **kwargs)

set_value(state, value, **kwargs)

check_value_get(value)

check_value_set(value, arch)

refine(size, arch=None, offset=None, is_fp=None)

class angr.calling_conventions.SimArrayArg(locs)

Bases: SimFunctionArgument

__init__(locs)

get_footprint()

Return a list of SimRegArg and SimStackArgs that are the base components used for this location

get_value(state, **kwargs)

set_value(state, value, **kwargs)

check_value_get(value)

check_value_set(value, arch)

refine(size, arch=None, offset=None, is_fp=None)

class angr.calling_conventions.SimReferenceArgument(ptr_loc, main_loc)

Bases: SimFunctionArgument

A function argument which is passed by reference.

Variables:

• ptr_loc – The location the reference’s pointer is stored

• main_loc – A SimStackArgument describing how to load the argument’s value as if it were stored at offset zero on the stack. It will be passed stack_base=ptr_loc.get_value(state)

__init__(ptr_loc, main_loc)

get_footprint()

Return a list of SimRegArg and SimStackArgs that are the base components used for this location

get_value(state, **kwargs)

set_value(state, value, **kwargs)

check_value_get(value)

check_value_set(value, arch)

refine(size, arch=None, offset=None, is_fp=None)

class angr.calling_conventions.ArgSession(cc)

Bases: object

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

__init__(cc)

cc

fp_iter

int_iter

both_iter

getstate()

setstate(state)

class angr.calling_conventions.UsercallArgSession(cc)

Bases: object

An argsession for use with SimCCUsercall

__init__(cc)

cc

real_args

getstate()

setstate(state)

class angr.calling_conventions.SimCC(arch)

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.

Parameters:

arch (Arch) –

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

ARG_REGS: List[str] = []

FP_ARG_REGS: List[str] = []

STACKARG_SP_BUFF = 0

STACKARG_SP_DIFF = 0

CALLER_SAVED_REGS: List[str] = []

RETURN_ADDR: SimFunctionArgument = None

RETURN_VAL: SimFunctionArgument = None

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

FP_RETURN_VAL: Optional[SimFunctionArgument] = None

ARCH = None

CALLEE_CLEANUP = False

STACK_ALIGNMENT = 1

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

Returns an iterator of SimFunctionArguments

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

return_in_implicit_outparam(ty)

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(ty, perspective_returned=False)

The location the return value is stored, based on its type.

property return_addr

The location the return address is stored.

next_arg(session, arg_type)

Parameters:

• session (ArgSession) –

• arg_type (SimType) –

static is_fp_value(val)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

get_args(state, prototype, stack_base=None)

set_return_val(state, val, ty, stack_base=None, perspective_returned=False)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

class angr.calling_conventions.SimLyingRegArg(name, size=8)

Bases: SimRegArg

A register that LIES about the types it holds

__init__(name, size=8)

get_value(state, **kwargs)

set_value(state, val, **kwargs)

refine(size, arch=None, offset=None, is_fp=None)

check_offset(arch)

check_value_get(value)

check_value_set(value, arch)

get_footprint()

Return a list of SimRegArg and SimStackArgs that are the base components used for this location

sse_extend()

class angr.calling_conventions.SimCCUsercall(arch, args, ret_loc)

Bases: SimCC

__init__(arch, args, ret_loc)

Parameters:

arch – The Archinfo arch for this CC

ArgSession

alias of UsercallArgSession

next_arg(session, arg_type)

return_val(ty, **kwargs)

The location the return value is stored, based on its type.

ARCH = None

ARG_REGS: List[str] = []

CALLEE_CLEANUP = False

CALLER_SAVED_REGS: List[str] = []

FP_ARG_REGS: List[str] = []

FP_RETURN_VAL: Optional[SimFunctionArgument] = None

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

RETURN_ADDR: SimFunctionArgument = None

RETURN_VAL: SimFunctionArgument = None

STACKARG_SP_BUFF = 0

STACKARG_SP_DIFF = 0

STACK_ALIGNMENT = 1

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

set_return_val(state, val, ty, stack_base=None, perspective_returned=False)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.calling_conventions.SimCCCdecl(arch)

Bases: SimCC

Parameters:

arch (Arch) –

ARG_REGS: List[str] = []

FP_ARG_REGS: List[str] = []

STACKARG_SP_DIFF = 4

CALLER_SAVED_REGS: List[str] = ['eax', 'ecx', 'edx']

RETURN_VAL: SimFunctionArgument = <eax>

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = <edx>

FP_RETURN_VAL: Optional[SimFunctionArgument] = <st0>

RETURN_ADDR: SimFunctionArgument = [0x0]

ARCH

alias of ArchX86

next_arg(session, arg_type)

STRUCT_RETURN_THRESHOLD = 32

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

return_in_implicit_outparam(ty)

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

STACKARG_SP_BUFF = 0

STACK_ALIGNMENT = 1

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

property return_addr

The location the return address is stored.

set_return_val(state, val, ty, stack_base=None, perspective_returned=False)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.calling_conventions.SimCCMicrosoftCdecl(arch)

Bases: SimCCCdecl

Parameters:

arch (Arch) –

STRUCT_RETURN_THRESHOLD = 64

ARCH

alias of ArchX86

ARG_REGS: List[str] = []

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

CALLER_SAVED_REGS: List[str] = ['eax', 'ecx', 'edx']

FP_ARG_REGS: List[str] = []

FP_RETURN_VAL: Optional[SimFunctionArgument] = <st0>

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = <edx>

RETURN_ADDR: SimFunctionArgument = [0x0]

RETURN_VAL: SimFunctionArgument = <eax>

STACKARG_SP_BUFF = 0

STACKARG_SP_DIFF = 4

STACK_ALIGNMENT = 1

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

next_arg(session, arg_type)

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, stack_base=None, perspective_returned=False)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.calling_conventions.SimCCStdcall(arch)

Bases: SimCCMicrosoftCdecl

Parameters:

arch (Arch) –

CALLEE_CLEANUP = True

ARCH

alias of ArchX86

ARG_REGS: List[str] = []

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLER_SAVED_REGS: List[str] = ['eax', 'ecx', 'edx']

FP_ARG_REGS: List[str] = []

FP_RETURN_VAL: Optional[SimFunctionArgument] = <st0>

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = <edx>

RETURN_ADDR: SimFunctionArgument = [0x0]

RETURN_VAL: SimFunctionArgument = <eax>

STACKARG_SP_BUFF = 0

STACKARG_SP_DIFF = 4

STACK_ALIGNMENT = 1

STRUCT_RETURN_THRESHOLD = 64

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

next_arg(session, arg_type)

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, stack_base=None, perspective_returned=False)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.calling_conventions.SimCCMicrosoftFastcall(arch)

Bases: SimCC

Parameters:

arch (Arch) –

ARG_REGS: List[str] = ['ecx', 'edx']

STACKARG_SP_DIFF = 4

RETURN_VAL: SimFunctionArgument = <eax>

RETURN_ADDR: SimFunctionArgument = [0x0]

ARCH

alias of ArchX86

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

CALLER_SAVED_REGS: List[str] = []

FP_ARG_REGS: List[str] = []

FP_RETURN_VAL: Optional[SimFunctionArgument] = None

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

STACKARG_SP_BUFF = 0

STACK_ALIGNMENT = 1

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

next_arg(session, arg_type)

Parameters:

• session (ArgSession) –

• arg_type (SimType) –

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, stack_base=None, perspective_returned=False)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.calling_conventions.MicrosoftAMD64ArgSession(cc)

Bases: object

__init__(cc)

class angr.calling_conventions.SimCCMicrosoftAMD64(arch)

Bases: SimCC

Parameters:

arch (Arch) –

ARG_REGS: List[str] = ['rcx', 'rdx', 'r8', 'r9']

FP_ARG_REGS: List[str] = ['xmm0', 'xmm1', 'xmm2', 'xmm3']

STACKARG_SP_DIFF = 8

STACKARG_SP_BUFF = 32

RETURN_VAL: SimFunctionArgument = <rax>

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = <rdx>

FP_RETURN_VAL: Optional[SimFunctionArgument] = <xmm0>

RETURN_ADDR: SimFunctionArgument = [0x0]

ARCH

alias of ArchAMD64

STACK_ALIGNMENT = 16

ArgSession

alias of MicrosoftAMD64ArgSession

next_arg(session, arg_type)

return_in_implicit_outparam(ty)

CALLEE_CLEANUP = False

CALLER_SAVED_REGS: List[str] = []

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

property return_addr

The location the return address is stored.

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, stack_base=None, perspective_returned=False)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.calling_conventions.SimCCSyscall(arch)

Bases: SimCC

The base class of all syscall CCs.

Parameters:

arch (Arch) –

ERROR_REG: SimRegArg = None

SYSCALL_ERRNO_START = None

static syscall_num(state)

Return type:

int

linux_syscall_update_error_reg(state, expr)

set_return_val(state, val, ty, **kwargs)

ARCH = None

ARG_REGS: List[str] = []

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

CALLER_SAVED_REGS: List[str] = []

FP_ARG_REGS: List[str] = []

FP_RETURN_VAL: Optional[SimFunctionArgument] = None

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

RETURN_ADDR: SimFunctionArgument = None

RETURN_VAL: SimFunctionArgument = None

STACKARG_SP_BUFF = 0

STACKARG_SP_DIFF = 0

STACK_ALIGNMENT = 1

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

next_arg(session, arg_type)

Parameters:

• session (ArgSession) –

• arg_type (SimType) –

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.calling_conventions.SimCCX86LinuxSyscall(arch)

Bases: SimCCSyscall

Parameters:

arch (Arch) –

ARG_REGS: List[str] = ['ebx', 'ecx', 'edx', 'esi', 'edi', 'ebp']

FP_ARG_REGS: List[str] = []

RETURN_VAL: SimFunctionArgument = <eax>

RETURN_ADDR: SimFunctionArgument = <ip_at_syscall>

ARCH

alias of ArchX86

static syscall_num(state)

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

CALLER_SAVED_REGS: List[str] = []

ERROR_REG: SimRegArg = None

FP_RETURN_VAL: Optional[SimFunctionArgument] = None

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

STACKARG_SP_BUFF = 0

STACKARG_SP_DIFF = 0

STACK_ALIGNMENT = 1

SYSCALL_ERRNO_START = None

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

linux_syscall_update_error_reg(state, expr)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

next_arg(session, arg_type)

Parameters:

• session (ArgSession) –

• arg_type (SimType) –

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, **kwargs)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.calling_conventions.SimCCX86WindowsSyscall(arch)

Bases: SimCCSyscall

Parameters:

arch (Arch) –

ARG_REGS: List[str] = []

FP_ARG_REGS: List[str] = []

RETURN_VAL: SimFunctionArgument = <eax>

RETURN_ADDR: SimFunctionArgument = <ip_at_syscall>

ARCH

alias of ArchX86

static syscall_num(state)

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

CALLER_SAVED_REGS: List[str] = []

ERROR_REG: SimRegArg = None

FP_RETURN_VAL: Optional[SimFunctionArgument] = None

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

STACKARG_SP_BUFF = 0

STACKARG_SP_DIFF = 0

STACK_ALIGNMENT = 1

SYSCALL_ERRNO_START = None

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

linux_syscall_update_error_reg(state, expr)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

next_arg(session, arg_type)

Parameters:

• session (ArgSession) –

• arg_type (SimType) –

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, **kwargs)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.calling_conventions.SimCCSystemVAMD64(arch)

Bases: SimCC

Parameters:

arch (Arch) –

ARG_REGS: List[str] = ['rdi', 'rsi', 'rdx', 'rcx', 'r8', 'r9']

FP_ARG_REGS: List[str] = ['xmm0', 'xmm1', 'xmm2', 'xmm3', 'xmm4', 'xmm5', 'xmm6', 'xmm7']

STACKARG_SP_DIFF = 8

CALLER_SAVED_REGS: List[str] = ['rdi', 'rsi', 'rdx', 'rcx', 'r8', 'r9', 'r10', 'r11', 'rax']

RETURN_ADDR: SimFunctionArgument = [0x0]

RETURN_VAL: SimFunctionArgument = <rax>

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = <rdx>

FP_RETURN_VAL: Optional[SimFunctionArgument] = <xmm0>

OVERFLOW_FP_RETURN_VAL = <xmm1>

ARCH

alias of ArchAMD64

STACK_ALIGNMENT = 16

next_arg(session, arg_type)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

Parameters:

ty (SimType | None) –

return_in_implicit_outparam(ty)

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

STACKARG_SP_BUFF = 0

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

property return_addr

The location the return address is stored.

set_return_val(state, val, ty, stack_base=None, perspective_returned=False)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.calling_conventions.SimCCAMD64LinuxSyscall(arch)

Bases: SimCCSyscall

Parameters:

arch (Arch) –

ARG_REGS: List[str] = ['rdi', 'rsi', 'rdx', 'r10', 'r8', 'r9']

RETURN_VAL: SimFunctionArgument = <rax>

RETURN_ADDR: SimFunctionArgument = <ip_at_syscall>

ARCH

alias of ArchAMD64

static syscall_num(state)

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

CALLER_SAVED_REGS: List[str] = []

ERROR_REG: SimRegArg = None

FP_ARG_REGS: List[str] = []

FP_RETURN_VAL: Optional[SimFunctionArgument] = None

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

STACKARG_SP_BUFF = 0

STACKARG_SP_DIFF = 0

STACK_ALIGNMENT = 1

SYSCALL_ERRNO_START = None

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

linux_syscall_update_error_reg(state, expr)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

next_arg(session, arg_type)

Parameters:

• session (ArgSession) –

• arg_type (SimType) –

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, **kwargs)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.calling_conventions.SimCCAMD64WindowsSyscall(arch)

Bases: SimCCSyscall

Parameters:

arch (Arch) –

ARG_REGS: List[str] = []

FP_ARG_REGS: List[str] = []

RETURN_VAL: SimFunctionArgument = <rax>

RETURN_ADDR: SimFunctionArgument = <ip_at_syscall>

ARCH

alias of ArchAMD64

static syscall_num(state)

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

CALLER_SAVED_REGS: List[str] = []

ERROR_REG: SimRegArg = None

FP_RETURN_VAL: Optional[SimFunctionArgument] = None

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

STACKARG_SP_BUFF = 0

STACKARG_SP_DIFF = 0

STACK_ALIGNMENT = 1

SYSCALL_ERRNO_START = None

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

linux_syscall_update_error_reg(state, expr)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

next_arg(session, arg_type)

Parameters:

• session (ArgSession) –

• arg_type (SimType) –

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, **kwargs)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.calling_conventions.SimCCARM(arch)

Bases: SimCC

Parameters:

arch (Arch) –

ARG_REGS: List[str] = ['r0', 'r1', 'r2', 'r3']

FP_ARG_REGS: List[str] = []

CALLER_SAVED_REGS: List[str] = []

RETURN_ADDR: SimFunctionArgument = <lr>

RETURN_VAL: SimFunctionArgument = <r0>

ARCH

alias of ArchARM

next_arg(session, arg_type)

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

FP_RETURN_VAL: Optional[SimFunctionArgument] = None

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

STACKARG_SP_BUFF = 0

STACKARG_SP_DIFF = 0

STACK_ALIGNMENT = 1

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, stack_base=None, perspective_returned=False)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.calling_conventions.SimCCARMHF(arch)

Bases: SimCCARM

Parameters:

arch (Arch) –

ARG_REGS: List[str] = ['r0', 'r1', 'r2', 'r3']

FP_ARG_REGS: List[str] = ['s0', 's1', 's2', 's3', 's4', 's5', 's6', 's7', 's8', 's9', 's10', 's11', 's12', 's13', 's14', 's15']

FP_RETURN_VAL: Optional[SimFunctionArgument] = <s0>

CALLER_SAVED_REGS: List[str] = []

RETURN_ADDR: SimFunctionArgument = <lr>

RETURN_VAL: SimFunctionArgument = <r0>

ARCH

alias of ArchARMHF

next_arg(session, arg_type)

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

STACKARG_SP_BUFF = 0

STACKARG_SP_DIFF = 0

STACK_ALIGNMENT = 1

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, stack_base=None, perspective_returned=False)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.calling_conventions.SimCCARMLinuxSyscall(arch)

Bases: SimCCSyscall

Parameters:

arch (Arch) –

ARG_REGS: List[str] = ['r0', 'r1', 'r2', 'r3']

FP_ARG_REGS: List[str] = []

RETURN_ADDR: SimFunctionArgument = <ip_at_syscall>

RETURN_VAL: SimFunctionArgument = <r0>

ARCH

alias of ArchARM

static syscall_num(state)

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

CALLER_SAVED_REGS: List[str] = []

ERROR_REG: SimRegArg = None

FP_RETURN_VAL: Optional[SimFunctionArgument] = None

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

STACKARG_SP_BUFF = 0

STACKARG_SP_DIFF = 0

STACK_ALIGNMENT = 1

SYSCALL_ERRNO_START = None

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

linux_syscall_update_error_reg(state, expr)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

next_arg(session, arg_type)

Parameters:

• session (ArgSession) –

• arg_type (SimType) –

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, **kwargs)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.calling_conventions.SimCCAArch64(arch)

Bases: SimCC

Parameters:

arch (Arch) –

ARG_REGS: List[str] = ['x0', 'x1', 'x2', 'x3', 'x4', 'x5', 'x6', 'x7']

FP_ARG_REGS: List[str] = []

RETURN_ADDR: SimFunctionArgument = <lr>

RETURN_VAL: SimFunctionArgument = <x0>

ARCH

alias of ArchAArch64

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

CALLER_SAVED_REGS: List[str] = []

FP_RETURN_VAL: Optional[SimFunctionArgument] = None

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

STACKARG_SP_BUFF = 0

STACKARG_SP_DIFF = 0

STACK_ALIGNMENT = 1

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

next_arg(session, arg_type)

Parameters:

• session (ArgSession) –

• arg_type (SimType) –

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, stack_base=None, perspective_returned=False)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.calling_conventions.SimCCAArch64LinuxSyscall(arch)

Bases: SimCCSyscall

Parameters:

arch (Arch) –

ARG_REGS: List[str] = ['x0', 'x1', 'x2', 'x3', 'x4', 'x5', 'x6', 'x7']

FP_ARG_REGS: List[str] = []

RETURN_VAL: SimFunctionArgument = <x0>

RETURN_ADDR: SimFunctionArgument = <ip_at_syscall>

ARCH

alias of ArchAArch64

static syscall_num(state)

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

CALLER_SAVED_REGS: List[str] = []

ERROR_REG: SimRegArg = None

FP_RETURN_VAL: Optional[SimFunctionArgument] = None

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

STACKARG_SP_BUFF = 0

STACKARG_SP_DIFF = 0

STACK_ALIGNMENT = 1

SYSCALL_ERRNO_START = None

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

linux_syscall_update_error_reg(state, expr)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

next_arg(session, arg_type)

Parameters:

• session (ArgSession) –

• arg_type (SimType) –

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, **kwargs)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.calling_conventions.SimCCO32(arch)

Bases: SimCC

Parameters:

arch (Arch) –

ARG_REGS: List[str] = ['a0', 'a1', 'a2', 'a3']

FP_ARG_REGS: List[str] = ['f12', 'f13', 'f14', 'f15']

STACKARG_SP_BUFF = 16

CALLER_SAVED_REGS: List[str] = ['t9', 'gp']

RETURN_ADDR: SimFunctionArgument = <ra>

RETURN_VAL: SimFunctionArgument = <v0>

ARCH

alias of ArchMIPS32

next_arg(session, arg_type)

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

FP_RETURN_VAL: Optional[SimFunctionArgument] = None

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

STACKARG_SP_DIFF = 0

STACK_ALIGNMENT = 1

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, stack_base=None, perspective_returned=False)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.calling_conventions.SimCCO32LinuxSyscall(arch)

Bases: SimCCSyscall

Parameters:

arch (Arch) –

ARG_REGS: List[str] = ['a0', 'a1', 'a2', 'a3']

FP_ARG_REGS: List[str] = []

RETURN_VAL: SimFunctionArgument = <v0>

RETURN_ADDR: SimFunctionArgument = <ip_at_syscall>

ARCH

alias of ArchMIPS32

ERROR_REG: SimRegArg = <a3>

SYSCALL_ERRNO_START = -1133

static syscall_num(state)

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

CALLER_SAVED_REGS: List[str] = []

FP_RETURN_VAL: Optional[SimFunctionArgument] = None

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

STACKARG_SP_BUFF = 0

STACKARG_SP_DIFF = 0

STACK_ALIGNMENT = 1

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

linux_syscall_update_error_reg(state, expr)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

next_arg(session, arg_type)

Parameters:

• session (ArgSession) –

• arg_type (SimType) –

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, **kwargs)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.calling_conventions.SimCCO64(arch)

Bases: SimCC

Parameters:

arch (Arch) –

ARG_REGS: List[str] = ['a0', 'a1', 'a2', 'a3']

CALLER_SAVED_REGS: List[str] = ['t9', 'gp']

FP_ARG_REGS: List[str] = []

STACKARG_SP_BUFF = 32

RETURN_ADDR: SimFunctionArgument = <ra>

RETURN_VAL: SimFunctionArgument = <v0>

ARCH

alias of ArchMIPS64

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

FP_RETURN_VAL: Optional[SimFunctionArgument] = None

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

STACKARG_SP_DIFF = 0

STACK_ALIGNMENT = 1

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

next_arg(session, arg_type)

Parameters:

• session (ArgSession) –

• arg_type (SimType) –

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, stack_base=None, perspective_returned=False)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.calling_conventions.SimCCO64LinuxSyscall(arch)

Bases: SimCCSyscall

Parameters:

arch (Arch) –

ARG_REGS: List[str] = ['a0', 'a1', 'a2', 'a3', 'a4', 'a5', 'a6', 'a7']

FP_ARG_REGS: List[str] = []

RETURN_VAL: SimFunctionArgument = <v0>

RETURN_ADDR: SimFunctionArgument = <ip_at_syscall>

ARCH

alias of ArchMIPS64

ERROR_REG: SimRegArg = <a3>

SYSCALL_ERRNO_START = -1133

static syscall_num(state)

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

CALLER_SAVED_REGS: List[str] = []

FP_RETURN_VAL: Optional[SimFunctionArgument] = None

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

STACKARG_SP_BUFF = 0

STACKARG_SP_DIFF = 0

STACK_ALIGNMENT = 1

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

linux_syscall_update_error_reg(state, expr)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

next_arg(session, arg_type)

Parameters:

• session (ArgSession) –

• arg_type (SimType) –

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, **kwargs)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.calling_conventions.SimCCPowerPC(arch)

Bases: SimCC

Parameters:

arch (Arch) –

ARG_REGS: List[str] = ['r3', 'r4', 'r5', 'r6', 'r7', 'r8', 'r9', 'r10']

FP_ARG_REGS: List[str] = []

STACKARG_SP_BUFF = 8

RETURN_ADDR: SimFunctionArgument = <lr>

RETURN_VAL: SimFunctionArgument = <r3>

ARCH

alias of ArchPPC32

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

CALLER_SAVED_REGS: List[str] = []

FP_RETURN_VAL: Optional[SimFunctionArgument] = None

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

STACKARG_SP_DIFF = 0

STACK_ALIGNMENT = 1

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

next_arg(session, arg_type)

Parameters:

• session (ArgSession) –

• arg_type (SimType) –

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, stack_base=None, perspective_returned=False)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.calling_conventions.SimCCPowerPCLinuxSyscall(arch)

Bases: SimCCSyscall

Parameters:

arch (Arch) –

ARG_REGS: List[str] = ['r3', 'r4', 'r5', 'r6', 'r7', 'r8', 'r9', 'r10']

FP_ARG_REGS: List[str] = []

RETURN_VAL: SimFunctionArgument = <r3>

RETURN_ADDR: SimFunctionArgument = <ip_at_syscall>

ARCH

alias of ArchPPC32

ERROR_REG: SimRegArg = <cr0_0>

SYSCALL_ERRNO_START = -515

static syscall_num(state)

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

CALLER_SAVED_REGS: List[str] = []

FP_RETURN_VAL: Optional[SimFunctionArgument] = None

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

STACKARG_SP_BUFF = 0

STACKARG_SP_DIFF = 0

STACK_ALIGNMENT = 1

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

linux_syscall_update_error_reg(state, expr)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

next_arg(session, arg_type)

Parameters:

• session (ArgSession) –

• arg_type (SimType) –

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, **kwargs)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.calling_conventions.SimCCPowerPC64(arch)

Bases: SimCC

Parameters:

arch (Arch) –

ARG_REGS: List[str] = ['r3', 'r4', 'r5', 'r6', 'r7', 'r8', 'r9', 'r10']

FP_ARG_REGS: List[str] = []

STACKARG_SP_BUFF = 112

RETURN_ADDR: SimFunctionArgument = <lr>

RETURN_VAL: SimFunctionArgument = <r3>

ARCH

alias of ArchPPC64

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

CALLER_SAVED_REGS: List[str] = []

FP_RETURN_VAL: Optional[SimFunctionArgument] = None

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

STACKARG_SP_DIFF = 0

STACK_ALIGNMENT = 1

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

next_arg(session, arg_type)

Parameters:

• session (ArgSession) –

• arg_type (SimType) –

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, stack_base=None, perspective_returned=False)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.calling_conventions.SimCCPowerPC64LinuxSyscall(arch)

Bases: SimCCSyscall

Parameters:

arch (Arch) –

ARG_REGS: List[str] = ['r3', 'r4', 'r5', 'r6', 'r7', 'r8', 'r9', 'r10']

FP_ARG_REGS: List[str] = []

RETURN_VAL: SimFunctionArgument = <r3>

RETURN_ADDR: SimFunctionArgument = <ip_at_syscall>

ARCH

alias of ArchPPC64

ERROR_REG: SimRegArg = <cr0_0>

SYSCALL_ERRNO_START = -515

static syscall_num(state)

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

CALLER_SAVED_REGS: List[str] = []

FP_RETURN_VAL: Optional[SimFunctionArgument] = None

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

STACKARG_SP_BUFF = 0

STACKARG_SP_DIFF = 0

STACK_ALIGNMENT = 1

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

linux_syscall_update_error_reg(state, expr)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

next_arg(session, arg_type)

Parameters:

• session (ArgSession) –

• arg_type (SimType) –

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, **kwargs)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.calling_conventions.SimCCSoot(arch)

Bases: SimCC

Parameters:

arch (Arch) –

ARCH

alias of ArchSoot

ARG_REGS: List[str] = []

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

CALLER_SAVED_REGS: List[str] = []

FP_ARG_REGS: List[str] = []

FP_RETURN_VAL: Optional[SimFunctionArgument] = None

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

RETURN_ADDR: SimFunctionArgument = None

RETURN_VAL: SimFunctionArgument = None

STACKARG_SP_BUFF = 0

STACKARG_SP_DIFF = 0

STACK_ALIGNMENT = 1

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

next_arg(session, arg_type)

Parameters:

• session (ArgSession) –

• arg_type (SimType) –

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, stack_base=None, perspective_returned=False)

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.calling_conventions.SimCCUnknown(arch)

Bases: SimCC

Represent an unknown calling convention.

Parameters:

arch (Arch) –

ARCH = None

ARG_REGS: List[str] = []

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

CALLER_SAVED_REGS: List[str] = []

FP_ARG_REGS: List[str] = []

FP_RETURN_VAL: Optional[SimFunctionArgument] = None

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

RETURN_ADDR: SimFunctionArgument = None

RETURN_VAL: SimFunctionArgument = None

STACKARG_SP_BUFF = 0

STACKARG_SP_DIFF = 0

STACK_ALIGNMENT = 1

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

next_arg(session, arg_type)

Parameters:

• session (ArgSession) –

• arg_type (SimType) –

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, stack_base=None, perspective_returned=False)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.calling_conventions.SimCCS390X(arch)

Bases: SimCC

Parameters:

arch (Arch) –

ARG_REGS: List[str] = ['r2', 'r3', 'r4', 'r5', 'r6']

FP_ARG_REGS: List[str] = ['f0', 'f2', 'f4', 'f6']

STACKARG_SP_BUFF = 160

RETURN_ADDR: SimFunctionArgument = <r14>

RETURN_VAL: SimFunctionArgument = <r2>

ARCH

alias of ArchS390X

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

CALLER_SAVED_REGS: List[str] = []

FP_RETURN_VAL: Optional[SimFunctionArgument] = None

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

STACKARG_SP_DIFF = 0

STACK_ALIGNMENT = 1

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

next_arg(session, arg_type)

Parameters:

• session (ArgSession) –

• arg_type (SimType) –

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, stack_base=None, perspective_returned=False)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

class angr.calling_conventions.SimCCS390XLinuxSyscall(arch)

Bases: SimCCSyscall

Parameters:

arch (Arch) –

ARG_REGS: List[str] = ['r2', 'r3', 'r4', 'r5', 'r6', 'r7']

FP_ARG_REGS: List[str] = []

RETURN_VAL: SimFunctionArgument = <r2>

RETURN_ADDR: SimFunctionArgument = <ip_at_syscall>

ARCH

alias of ArchS390X

static syscall_num(state)

class ArgSession(cc)

Bases: object

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

cc

fp_iter

int_iter

both_iter

__init__(cc)

getstate()

setstate(state)

CALLEE_CLEANUP = False

CALLER_SAVED_REGS: List[str] = []

ERROR_REG: SimRegArg = None

FP_RETURN_VAL: Optional[SimFunctionArgument] = None

OVERFLOW_RETURN_VAL: Optional[SimFunctionArgument] = None

STACKARG_SP_BUFF = 0

STACKARG_SP_DIFF = 0

STACK_ALIGNMENT = 1

SYSCALL_ERRNO_START = None

__init__(arch)

Parameters:

arch (Arch) – The Archinfo arch for this CC

arg_locs(prototype)

Return type:

List[SimFunctionArgument]

arg_session(ret_ty)

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.

You need to provide the return type of the function in order to kick off an arg layout session.

Parameters:

ret_ty (SimType | None) –

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[SimFunctionArgument]) – A list of arguments. It may be updated by the first matched calling convention to remove non-argument arguments.

• sp_delta (int) – The change of stack pointer before and after the call is made.

Return type:

Optional[SimCC]

Returns:

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

property fp_args

Iterate through all the possible arg positions that can only be used to store floating point values.

Returns an iterator of SimFunctionArguments

get_arg_info(state, prototype)

This is just a simple wrapper that collects the information from various locations prototype is as passed to self.arg_locs and self.get_args :param angr.SimState state: The state to evaluate and extract the values from :return: A list of tuples, where the nth tuple is (type, name, location, value) of the nth argument

get_args(state, prototype, stack_base=None)

static guess_prototype(args, prototype=None)

Come up with a plausible SimTypeFunction for the given args (as would be passed to e.g. setup_callsite).

You can pass a variadic function prototype in the base_type parameter and all its arguments will be used, only guessing types for the variadic arguments.

property int_args

Iterate through all the possible arg positions that can only be used to store integer or pointer values.

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.

static is_fp_value(val)

linux_syscall_update_error_reg(state, expr)

property memory_args

Iterate through all the possible arg positions that can be used to store any kind of argument.

Returns an iterator of SimFunctionArguments

next_arg(session, arg_type)

Parameters:

• session (ArgSession) –

• arg_type (SimType) –

property return_addr

The location the return address is stored.

return_in_implicit_outparam(ty)

return_val(ty, perspective_returned=False)

The location the return value is stored, based on its type.

set_return_val(state, val, ty, **kwargs)

setup_callsite(state, ret_addr, args, prototype, 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

• prototype – The signature of the call you’re making. Should include variadic args concretely.

• 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.

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 stack base will be used and grow_like_stack will implicitly be True.

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

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.

teardown_callsite(state, return_val=None, prototype=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

• prototype – The prototype of the given function

• 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?

angr.calling_conventions.register_default_cc(arch, cc)

Parameters:

• arch (str) –

• cc (Type[SimCC]) –

angr.calling_conventions.default_cc(arch, platform=None, language=None)

Return the default calling convention for a given architecture, platform, and language combination.

Parameters:

• arch (str) – The architecture name.

• platform (Optional[str]) – The platform name (e.g., “linux”).

• language (Optional[str]) – The programming language name (e.g., “go”).

Return type:

Optional[Type[SimCC]]

Returns:

A default calling convention class if we can find one for the architecture, platform, and language combination, or None if nothing fits.

angr.calling_conventions.unify_arch_name(arch)

Return the unified architecture name.

Parameters:

arch (str) – The architecture name.

Return type:

str

Returns:

A unified architecture name.

angr.calling_conventions.register_syscall_cc(arch, os, cc)

class angr.sim_variable.SimVariable(ident=None, name=None, region=None, category=None, size=None)

Bases: Serializable

Parameters:

• region (int | None) –

• size (int | None) –

__init__(ident=None, name=None, region=None, category=None, size=None)

Parameters:

• ident – A unique identifier provided by user or the program. Usually a string.

• name (str) – Name of this variable.

• region (int | None) –

• size (int | None) –

ident

name

region: Optional[int]

category: Optional[str]

renamed

candidate_names

size

copy()

loc_repr(arch)

The representation that shows up in a GUI

Parameters:

arch (Arch) –

property is_function_argument

classmethod parse(s, **kwargs)

Parse a bytes object and create a class object.

Parameters:

s (bytes) – A bytes object.

Returns:

A class object.

Return type:

cls

classmethod parse_from_cmessage(cmsg, **kwargs)

Parse a protobuf cmessage and create a class object.

Parameters:

cmsg – The probobuf cmessage object.

Returns:

A unserialized class object.

Return type:

cls

serialize()

Serialize the class object and returns a bytes object.

Returns:

A bytes object.

Return type:

bytes

serialize_to_cmessage()

Serialize the class object and returns a protobuf cmessage object.

Returns:

A protobuf cmessage object.

Return type:

protobuf.cmessage

class angr.sim_variable.SimConstantVariable(ident=None, value=None, region=None, size=None)

Bases: SimVariable

Parameters:

region (int | None) –

__init__(ident=None, value=None, region=None, size=None)

Parameters:

• ident – A unique identifier provided by user or the program. Usually a string.

• name (str) – Name of this variable.

value

loc_repr(arch)

The representation that shows up in a GUI

copy()

Return type:

SimConstantVariable

candidate_names

category: Optional[str]

ident

property is_function_argument

name

classmethod parse(s, **kwargs)

Parse a bytes object and create a class object.

Parameters:

s (bytes) – A bytes object.

Returns:

A class object.

Return type:

cls

classmethod parse_from_cmessage(cmsg, **kwargs)

Parse a protobuf cmessage and create a class object.

Parameters:

cmsg – The probobuf cmessage object.

Returns:

A unserialized class object.

Return type:

cls

region: Optional[int]

renamed

serialize()

Serialize the class object and returns a bytes object.

Returns:

A bytes object.

Return type:

bytes

serialize_to_cmessage()

Serialize the class object and returns a protobuf cmessage object.

Returns:

A protobuf cmessage object.

Return type:

protobuf.cmessage

size

class angr.sim_variable.SimTemporaryVariable(tmp_id, size=None)

Bases: SimVariable

__init__(tmp_id, size=None)

Parameters:

• ident – A unique identifier provided by user or the program. Usually a string.

• name (str) – Name of this variable.

tmp_id

loc_repr(arch)

The representation that shows up in a GUI

copy()

Return type:

SimTemporaryVariable

serialize_to_cmessage()

Serialize the class object and returns a protobuf cmessage object.

Returns:

A protobuf cmessage object.

Return type:

protobuf.cmessage

classmethod parse_from_cmessage(cmsg, **kwargs)

Parse a protobuf cmessage and create a class object.

Parameters:

cmsg – The probobuf cmessage object.

Returns:

A unserialized class object.

Return type:

cls

candidate_names

category: Optional[str]

ident

property is_function_argument

name

classmethod parse(s, **kwargs)

Parse a bytes object and create a class object.

Parameters:

s (bytes) – A bytes object.

Returns:

A class object.

Return type:

cls

region: Optional[int]

renamed

serialize()

Serialize the class object and returns a bytes object.

Returns:

A bytes object.

Return type:

bytes

size

class angr.sim_variable.SimRegisterVariable(reg_offset, size, ident=None, name=None, region=None, category=None)

Bases: SimVariable

Parameters:

• region (int | None) –

• category (str | None) –

__init__(reg_offset, size, ident=None, name=None, region=None, category=None)

Parameters:

• ident – A unique identifier provided by user or the program. Usually a string.

• name (str) – Name of this variable.

reg: int

property bits

loc_repr(arch)

The representation that shows up in a GUI

copy()

Return type:

SimRegisterVariable

serialize_to_cmessage()

Serialize the class object and returns a protobuf cmessage object.

Returns:

A protobuf cmessage object.

Return type:

protobuf.cmessage

classmethod parse_from_cmessage(cmsg, **kwargs)

Parse a protobuf cmessage and create a class object.

Parameters:

cmsg – The probobuf cmessage object.

Returns:

A unserialized class object.

Return type:

cls

candidate_names

category: Optional[str]

ident

property is_function_argument

name

classmethod parse(s, **kwargs)

Parse a bytes object and create a class object.

Parameters:

s (bytes) – A bytes object.

Returns:

A class object.

Return type:

cls

region: Optional[int]

renamed

serialize()

Serialize the class object and returns a bytes object.

Returns:

A bytes object.

Return type:

bytes

size

class angr.sim_variable.SimMemoryVariable(addr, size, ident=None, name=None, region=None, category=None)

Bases: SimVariable

Parameters:

• region (int | None) –

• category (str | None) –

__init__(addr, size, ident=None, name=None, region=None, category=None)

Parameters:

• ident – A unique identifier provided by user or the program. Usually a string.

• name (str) – Name of this variable.

addr

size

loc_repr(arch)

The representation that shows up in a GUI

property bits

copy()

Return type:

SimMemoryVariable

serialize_to_cmessage()

Serialize the class object and returns a protobuf cmessage object.

Returns:

A protobuf cmessage object.

Return type:

protobuf.cmessage

classmethod parse_from_cmessage(cmsg, **kwargs)

Parse a protobuf cmessage and create a class object.

Parameters:

cmsg – The probobuf cmessage object.

Returns:

A unserialized class object.

Return type:

cls

candidate_names

category: Optional[str]

ident

property is_function_argument

name

classmethod parse(s, **kwargs)

Parse a bytes object and create a class object.

Parameters:

s (bytes) – A bytes object.

Returns:

A class object.

Return type:

cls

region: Optional[int]

renamed

serialize()

Serialize the class object and returns a bytes object.

Returns:

A bytes object.

Return type:

bytes

class angr.sim_variable.SimStackVariable(offset, size, base='sp', base_addr=None, ident=None, name=None, region=None, category=None)

Bases: SimMemoryVariable

Parameters:

• region (int | None) –

• category (str | None) –

__init__(offset, size, base='sp', base_addr=None, ident=None, name=None, region=None, category=None)

Parameters:

• ident – A unique identifier provided by user or the program. Usually a string.

• name (str) – Name of this variable.

base

offset

base_addr

loc_repr(arch)

The representation that shows up in a GUI

copy()

Return type:

SimStackVariable

serialize_to_cmessage()

Serialize the class object and returns a protobuf cmessage object.

Returns:

A protobuf cmessage object.

Return type:

protobuf.cmessage

classmethod parse_from_cmessage(cmsg, **kwargs)

Parse a protobuf cmessage and create a class object.

Parameters:

cmsg – The probobuf cmessage object.

Returns:

A unserialized class object.

Return type:

cls

addr

property bits

candidate_names

category: Optional[str]

ident

property is_function_argument

name

classmethod parse(s, **kwargs)

Parse a bytes object and create a class object.

Parameters:

s (bytes) – A bytes object.

Returns:

A class object.

Return type:

cls

region: Optional[int]

renamed

serialize()

Serialize the class object and returns a bytes object.

Returns:

A bytes object.

Return type:

bytes

size

class angr.sim_variable.SimVariableSet

Bases: MutableSet

A collection of SimVariables.

__init__()

add(item)

Add an element.

add_register_variable(reg_var)

add_memory_variable(mem_var)

discard(item)

Remove an element. Do not raise an exception if absent.

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)

clear()

This is slow (creates N new iterators!) but effective.

isdisjoint(other)

Return True if two sets have a null intersection.

pop()

Return the popped value. Raise KeyError if empty.

remove(value)

Remove an element. If not a member, raise a KeyError.

class angr.sim_type.SimType(label=None)

Bases: object

SimType exists to track type information for SimProcedures.

base = True

__init__(label=None)

Parameters:

label – the type label.

property size

The size of the type in bits.

property alignment

The alignment of the type in bytes.

with_arch(arch)

c_repr(name=None, full=0, memo=None, indent=0)

copy()

extract_claripy(bits)

Given a bitvector bits which was loaded from memory in a big-endian fashion, return a more appropriate or structured representation of the data.

A type must have an arch associated in order to use this method.

class angr.sim_type.TypeRef(name, ty)

Bases: SimType

A TypeRef is a reference to a type with a name. This allows for interactivity in type analysis, by storing a type and having the option to update it later and have all references to it automatically update as well.

__init__(name, ty)

Parameters:

label – the type label.

property name

This is a read-only property because it is desirable to store typerefs in a mapping from name to type, and we want the mapping to be in the loop for any updates.

property size

The size of the type in bits.

property alignment

The alignment of the type in bytes.

with_arch(arch)

c_repr(name=None, full=0, memo=None, indent=0)

copy()

base = True

extract_claripy(bits)

Given a bitvector bits which was loaded from memory in a big-endian fashion, return a more appropriate or structured representation of the data.

A type must have an arch associated in order to use this method.

class angr.sim_type.NamedTypeMixin(*args, name=None, **kwargs)

Bases: object

SimType classes with this mixin in the class hierarchy allows setting custom class names. A typical use case is to represent same or similar type classes with different qualified names, such as “std::basic_string” vs “std::__cxx11::basic_string”. In such cases, .name stores the qualified name, and .unqualified_name() returns the unqualified name of the type.

Parameters:

name (str | None) –

__init__(*args, name=None, **kwargs)

Parameters:

name (str | None) –

property name: str

unqualified_name(lang='c++')

Return type:

str

Parameters:

lang (str) –

class angr.sim_type.SimTypeBottom(label=None)

Bases: SimType

SimTypeBottom basically represents a type error.

__init__(label=None)

Parameters:

label – the type label.

c_repr(name=None, full=0, memo=None, indent=0)

copy()

property alignment

The alignment of the type in bytes.

base = True

extract_claripy(bits)

Given a bitvector bits which was loaded from memory in a big-endian fashion, return a more appropriate or structured representation of the data.

A type must have an arch associated in order to use this method.

property size

The size of the type in bits.

with_arch(arch)

class angr.sim_type.SimTypeTop(size=None, label=None)

Bases: SimType

SimTypeTop represents any type (mostly used with a pointer for void*).

__init__(size=None, label=None)

Parameters:

label – the type label.

copy()

property alignment

The alignment of the type in bytes.

base = True

c_repr(name=None, full=0, memo=None, indent=0)

extract_claripy(bits)

Given a bitvector bits which was loaded from memory in a big-endian fashion, return a more appropriate or structured representation of the data.

A type must have an arch associated in order to use this method.

property size

The size of the type in bits.

with_arch(arch)

class angr.sim_type.SimTypeReg(size, label=None)

Bases: SimType

SimTypeReg is the base type for all types that are register-sized.

__init__(size, label=None)

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)

copy()

property alignment

The alignment of the type in bytes.

base = True

c_repr(name=None, full=0, memo=None, indent=0)

extract_claripy(bits)

Given a bitvector bits which was loaded from memory in a big-endian fashion, return a more appropriate or structured representation of the data.

A type must have an arch associated in order to use this method.

property size

The size of the type in bits.

with_arch(arch)

class angr.sim_type.SimTypeNum(size, signed=True, label=None)

Bases: SimType

SimTypeNum is a numeric type of arbitrary length

__init__(size, signed=True, label=None)

Parameters:

• size – The size of the integer, in bits

• signed – Whether the integer is signed or not

• label – A label for the type

extract(state, addr, concrete=False)

store(state, addr, value)

copy()

property alignment

The alignment of the type in bytes.

base = True

c_repr(name=None, full=0, memo=None, indent=0)

extract_claripy(bits)

Given a bitvector bits which was loaded from memory in a big-endian fashion, return a more appropriate or structured representation of the data.

A type must have an arch associated in order to use this method.

property size

The size of the type in bits.

with_arch(arch)

class angr.sim_type.SimTypeInt(signed=True, label=None)

Bases: SimTypeReg

SimTypeInt is a type that specifies a signed or unsigned C integer.

__init__(signed=True, label=None)

Parameters:

• signed – True if signed, False if unsigned

• label – The type label

c_repr(name=None, full=0, memo=None, indent=0)

property size

The size of the type in bits.

extract(state, addr, concrete=False)

copy()

property alignment

The alignment of the type in bytes.

base = True

extract_claripy(bits)

Given a bitvector bits which was loaded from memory in a big-endian fashion, return a more appropriate or structured representation of the data.

A type must have an arch associated in order to use this method.

store(state, addr, value)

with_arch(arch)

class angr.sim_type.SimTypeShort(signed=True, label=None)

Bases: SimTypeInt

__init__(signed=True, label=None)

Parameters:

• signed – True if signed, False if unsigned

• label – The type label

property alignment

The alignment of the type in bytes.

base = True

c_repr(name=None, full=0, memo=None, indent=0)

copy()

extract(state, addr, concrete=False)

extract_claripy(bits)

Given a bitvector bits which was loaded from memory in a big-endian fashion, return a more appropriate or structured representation of the data.

A type must have an arch associated in order to use this method.

property size

The size of the type in bits.

store(state, addr, value)

with_arch(arch)

class angr.sim_type.SimTypeLong(signed=True, label=None)

Bases: SimTypeInt

__init__(signed=True, label=None)

Parameters:

• signed – True if signed, False if unsigned

• label – The type label

property alignment

The alignment of the type in bytes.

base = True

c_repr(name=None, full=0, memo=None, indent=0)

copy()

extract(state, addr, concrete=False)

extract_claripy(bits)

Given a bitvector bits which was loaded from memory in a big-endian fashion, return a more appropriate or structured representation of the data.

A type must have an arch associated in order to use this method.

property size

The size of the type in bits.

store(state, addr, value)

with_arch(arch)

class angr.sim_type.SimTypeLongLong(signed=True, label=None)

Bases: SimTypeInt

__init__(signed=True, label=None)

Parameters:

• signed – True if signed, False if unsigned

• label – The type label

property alignment

The alignment of the type in bytes.

base = True

c_repr(name=None, full=0, memo=None, indent=0)

copy()

extract(state, addr, concrete=False)

extract_claripy(bits)

Given a bitvector bits which was loaded from memory in a big-endian fashion, return a more appropriate or structured representation of the data.

A type must have an arch associated in order to use this method.

property size

The size of the type in bits.

store(state, addr, value)

with_arch(arch)

class angr.sim_type.SimTypeChar(signed=True, label=None)

Bases: 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.

__init__(signed=True, label=None)

Parameters:

label – the type label.

store(state, addr, value)

extract(state, addr, concrete=False)

copy()

property alignment

The alignment of the type in bytes.

base = True

c_repr(name=None, full=0, memo=None, indent=0)

extract_claripy(bits)

Given a bitvector bits which was loaded from memory in a big-endian fashion, return a more appropriate or structured representation of the data.

A type must have an arch associated in order to use this method.

property size

The size of the type in bits.

with_arch(arch)

class angr.sim_type.SimTypeBool(signed=True, label=None)

Bases: SimTypeChar

store(state, addr, value)

extract(state, addr, concrete=False)

__init__(signed=True, label=None)

Parameters:

label – the type label.

property alignment

The alignment of the type in bytes.

base = True

c_repr(name=None, full=0, memo=None, indent=0)

copy()

extract_claripy(bits)

Given a bitvector bits which was loaded from memory in a big-endian fashion, return a more appropriate or structured representation of the data.

A type must have an arch associated in order to use this method.

property size

The size of the type in bits.

with_arch(arch)

class angr.sim_type.SimTypeFd(label=None)

Bases: SimTypeReg

SimTypeFd is a type that specifies a file descriptor.

__init__(label=None)

Parameters:

label – the type label

copy()

property alignment

The alignment of the type in bytes.

base = True

c_repr(name=None, full=0, memo=None, indent=0)

extract(state, addr, concrete=False)

extract_claripy(bits)

Given a bitvector bits which was loaded from memory in a big-endian fashion, return a more appropriate or structured representation of the data.

A type must have an arch associated in order to use this method.

property size

The size of the type in bits.

store(state, addr, value)

with_arch(arch)

class angr.sim_type.SimTypePointer(pts_to, label=None, offset=0)

Bases: SimTypeReg

SimTypePointer is a type that specifies a pointer to some other type.

__init__(pts_to, label=None, offset=0)

Parameters:

• label – The type label.

• pts_to – The type to which this pointer points.

c_repr(name=None, full=0, memo=None, indent=0)

make(pts_to)

property size

The size of the type in bits.

copy()

property alignment

The alignment of the type in bytes.

base = True

extract(state, addr, concrete=False)

extract_claripy(bits)

Given a bitvector bits which was loaded from memory in a big-endian fashion, return a more appropriate or structured representation of the data.

A type must have an arch associated in order to use this method.

store(state, addr, value)

with_arch(arch)

class angr.sim_type.SimTypeReference(refs, label=None)

Bases: SimTypeReg

SimTypeReference is a type that specifies a reference to some other type.

__init__(refs, label=None)

Parameters:

• label – the type label.

• size – the size of the type (e.g. 32bit, 8bit, etc.).

c_repr(name=None, full=0, memo=None, indent=0)

make(refs)

property size

The size of the type in bits.

copy()

property alignment

The alignment of the type in bytes.

base = True

extract(state, addr, concrete=False)

extract_claripy(bits)

Given a bitvector bits which was loaded from memory in a big-endian fashion, return a more appropriate or structured representation of the data.

A type must have an arch associated in order to use this method.

store(state, addr, value)

with_arch(arch)

class angr.sim_type.SimTypeArray(elem_type, length=None, label=None)

Bases: SimType

SimTypeArray is a type that specifies a series of data laid out in sequence.

__init__(elem_type, length=None, label=None)

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.

c_repr(name=None, full=0, memo=None, indent=0)

property size

The size of the type in bits.

property alignment

The alignment of the type in bytes.

copy()

extract(state, addr, concrete=False)

store(state, addr, values)

base = True

extract_claripy(bits)

Given a bitvector bits which was loaded from memory in a big-endian fashion, return a more appropriate or structured representation of the data.

A type must have an arch associated in order to use this method.

with_arch(arch)

angr.sim_type.SimTypeFixedSizeArray

alias of SimTypeArray

class angr.sim_type.SimTypeString(length=None, label=None, name=None)

Bases: NamedTypeMixin, SimTypeArray

SimTypeString is a type that represents a C-style string, i.e. a NUL-terminated array of bytes.

Parameters:

• length (int | None) –

• name (str | None) –

__init__(length=None, label=None, name=None)

Parameters:

• label – The type label.

• length – An expression of the length of the string, if known.

• name (str | None) –

extract(state, addr, concrete=False)

Parameters:

state (SimState) –

property size

The size of the type in bits.

property alignment

The alignment of the type in bytes.

copy()

base = True

c_repr(name=None, full=0, memo=None, indent=0)

extract_claripy(bits)

Given a bitvector bits which was loaded from memory in a big-endian fashion, return a more appropriate or structured representation of the data.

A type must have an arch associated in order to use this method.

property name: str

store(state, addr, values)

unqualified_name(lang='c++')

Return type:

str

Parameters:

lang (str) –

with_arch(arch)

elem_type: SimType

length: Optional[int]

class angr.sim_type.SimTypeWString(length=None, label=None, name=None)

Bases: NamedTypeMixin, SimTypeArray

A wide-character null-terminated string, where each character is 2 bytes.

Parameters:

• length (int | None) –

• name (str | None) –

__init__(length=None, label=None, name=None)

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.

• name (str | None) –

extract(state, addr, concrete=False)

property size

The size of the type in bits.

property alignment

The alignment of the type in bytes.

copy()

base = True

c_repr(name=None, full=0, memo=None, indent=0)

extract_claripy(bits)

Given a bitvector bits which was loaded from memory in a big-endian fashion, return a more appropriate or structured representation of the data.

A type must have an arch associated in order to use this method.

property name: str

store(state, addr, values)

unqualified_name(lang='c++')

Return type:

str

Parameters:

lang (str) –

with_arch(arch)

elem_type: SimType

length: Optional[int]

class angr.sim_type.SimTypeFunction(args, returnty, label=None, arg_names=None, variadic=False)

Bases: 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.

base = False

__init__(args, returnty, label=None, arg_names=None, variadic=False)

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

• variadic – Whether the function accepts varargs

c_repr(name=None, full=0, memo=None, indent=0)

property size

The size of the type in bits.

copy()

property alignment

The alignment of the type in bytes.

extract_claripy(bits)

Given a bitvector bits which was loaded from memory in a big-endian fashion, return a more appropriate or structured representation of the data.

A type must have an arch associated in order to use this method.

with_arch(arch)

class angr.sim_type.SimTypeCppFunction(args, returnty, label=None, arg_names=None, ctor=False, dtor=False)

Bases: SimTypeFunction

SimTypeCppFunction is a type that specifies an actual C++-style function with information about arguments, return value, and more C++-specific properties.

Variables:

• ctor – Whether the function is a constructor or not.

• dtor – Whether the function is a destructor or not.

Parameters:

• returnty (SimType | None) –

• arg_names (Tuple[str]) –

• ctor (bool) –

• dtor (bool) –

__init__(args, returnty, label=None, arg_names=None, ctor=False, dtor=False)

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

• variadic – Whether the function accepts varargs

• arg_names (Tuple[str] | None) –

• ctor (bool) –

• dtor (bool) –

copy()

property alignment

The alignment of the type in bytes.

base = False

c_repr(name=None, full=0, memo=None, indent=0)

extract_claripy(bits)

Given a bitvector bits which was loaded from memory in a big-endian fashion, return a more appropriate or structured representation of the data.

A type must have an arch associated in order to use this method.

property size

The size of the type in bits.

with_arch(arch)

returnty: Optional[SimType]

class angr.sim_type.SimTypeLength(signed=False, addr=None, length=None, label=None)

Bases: 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

__init__(signed=False, addr=None, length=None, label=None)

Parameters:

• signed – Whether the value is signed or not

• label – The type label.

• addr – The memory address (expression).

• length – The length (expression).

property size

The size of the type in bits.

copy()

property alignment

The alignment of the type in bytes.

base = True

c_repr(name=None, full=0, memo=None, indent=0)

extract(state, addr, concrete=False)

extract_claripy(bits)

Given a bitvector bits which was loaded from memory in a big-endian fashion, return a more appropriate or structured representation of the data.

A type must have an arch associated in order to use this method.

store(state, addr, value)

with_arch(arch)

class angr.sim_type.SimTypeFloat(size=32)

Bases: SimTypeReg

An IEEE754 single-precision floating point number

__init__(size=32)

Parameters:

• label – the type label.

• size – the size of the type (e.g. 32bit, 8bit, etc.).

sort = FLOAT

signed = True

extract(state, addr, concrete=False)

store(state, addr, value)

copy()

property alignment

The alignment of the type in bytes.

base = True

c_repr(name=None, full=0, memo=None, indent=0)

extract_claripy(bits)

Given a bitvector bits which was loaded from memory in a big-endian fashion, return a more appropriate or structured representation of the data.

A type must have an arch associated in order to use this method.

property size

The size of the type in bits.

with_arch(arch)

class angr.sim_type.SimTypeDouble(align_double=True)

Bases: SimTypeFloat

An IEEE754 double-precision floating point number

__init__(align_double=True)

Parameters:

• label – the type label.

• size – the size of the type (e.g. 32bit, 8bit, etc.).

sort = DOUBLE

property alignment

The alignment of the type in bytes.

copy()

base = True

c_repr(name=None, full=0, memo=None, indent=0)

extract(state, addr, concrete=False)

extract_claripy(bits)

Given a bitvector bits which was loaded from memory in a big-endian fashion, return a more appropriate or structured representation of the data.

A type must have an arch associated in order to use this method.

signed = True

property size

The size of the type in bits.

store(state, addr, value)

with_arch(arch)

class angr.sim_type.SimStruct(fields, name=None, pack=False, align=None)

Bases: NamedTypeMixin, SimType

Parameters:

fields (Dict[str, SimType] | OrderedDict) –

__init__(fields, name=None, pack=False, align=None)

Parameters:

• label – the type label.

• fields (Dict[str, SimType] | OrderedDict) –

property packed

property offsets: Dict[str, int]

extract(state, addr, concrete=False)

c_repr(name=None, full=0, memo=None, indent=0)

property size

The size of the type in bits.

property alignment

The alignment of the type in bytes.

store(state, addr, value)

copy()

base = True

extract_claripy(bits)

Given a bitvector bits which was loaded from memory in a big-endian fashion, return a more appropriate or structured representation of the data.

A type must have an arch associated in order to use this method.

property name: str

unqualified_name(lang='c++')

Return type:

str

Parameters:

lang (str) –

with_arch(arch)

class angr.sim_type.SimStructValue(struct, values=None)

Bases: object

A SimStruct type paired with some real values

__init__(struct, values=None)

Parameters:

• struct – A SimStruct instance describing the type of this struct

• values – A mapping from struct fields to values

property struct

copy()

class angr.sim_type.SimUnion(members, name=None, label=None)

Bases: NamedTypeMixin, SimType

fields = ('members', 'name')

__init__(members, name=None, label=None)

Parameters:

• members – The members of the union, as a mapping name -> type

• name – The name of the union

property size

The size of the type in bits.

property alignment

The alignment of the type in bytes.

extract(state, addr, concrete=False)

c_repr(name=None, full=0, memo=None, indent=0)

copy()

base = True

extract_claripy(bits)

Given a bitvector bits which was loaded from memory in a big-endian fashion, return a more appropriate or structured representation of the data.

A type must have an arch associated in order to use this method.

property name: str

unqualified_name(lang='c++')

Return type:

str

Parameters:

lang (str) –

with_arch(arch)

class angr.sim_type.SimUnionValue(union, values=None)

Bases: object

A SimStruct type paired with some real values

__init__(union, values=None)

Parameters:

• union – A SimUnion instance describing the type of this union

• values – A mapping from union members to values

copy()

class angr.sim_type.SimCppClass(members=None, function_members=None, vtable_ptrs=None, name=None, pack=False, align=None)

Bases: SimStruct

Parameters:

• members (Dict[str, SimType] | None) –

• function_members (Dict[str, SimTypeCppFunction] | None) –

• name (str | None) –

• pack (bool) –

__init__(members=None, function_members=None, vtable_ptrs=None, name=None, pack=False, align=None)

Parameters:

• label – the type label.

• members (Dict[str, SimType] | None) –

• function_members (Dict[str, SimTypeCppFunction] | None) –

• name (str | None) –

• pack (bool) –

property members

extract(state, addr, concrete=False)

store(state, addr, value)

copy()

property alignment

The alignment of the type in bytes.

base = True

c_repr(name=None, full=0, memo=None, indent=0)

extract_claripy(bits)

Given a bitvector bits which was loaded from memory in a big-endian fashion, return a more appropriate or structured representation of the data.

A type must have an arch associated in order to use this method.

property name: str

property offsets: Dict[str, int]

property packed

property size

The size of the type in bits.

unqualified_name(lang='c++')

Return type:

str

Parameters:

lang (str) –

with_arch(arch)

class angr.sim_type.SimCppClassValue(class_type, values)

Bases: object

A SimCppClass type paired with some real values

__init__(class_type, values)

copy()

class angr.sim_type.SimTypeNumOffset(size, signed=True, label=None, offset=0)

Bases: SimTypeNum

like SimTypeNum, but supports an offset of 1 to 7 to a byte aligned address to allow structs with bitfields

__init__(size, signed=True, label=None, offset=0)

Parameters:

• size – The size of the integer, in bits

• signed – Whether the integer is signed or not

• label – A label for the type

extract(state, addr, concrete=False)

Parameters:

state (SimState) –

store(state, addr, value)

copy()

property alignment

The alignment of the type in bytes.

base = True

c_repr(name=None, full=0, memo=None, indent=0)

extract_claripy(bits)

Given a bitvector bits which was loaded from memory in a big-endian fashion, return a more appropriate or structured representation of the data.

A type must have an arch associated in order to use this method.

property size

The size of the type in bits.

with_arch(arch)

angr.sim_type.register_types(types)

Pass in some types and they will be registered to the global type store.

The argument may be either a mapping from name to SimType, or a plain SimType. The plain SimType must be either a struct or union type with a name present.

>>> register_types(parse_types("typedef int x; typedef float y;"))
>>> register_types(parse_type("struct abcd { int ab; float cd; }"))

angr.sim_type.do_preprocess(defn, include_path=())

Run a string through the C preprocessor that ships with pycparser but is weirdly inaccessible?

angr.sim_type.parse_signature(defn, preprocess=True, predefined_types=None, arch=None)

Parse a single function prototype and return its type

angr.sim_type.parse_defns(defn, preprocess=True, predefined_types=None, arch=None)

Parse a series of C definitions, returns a mapping from variable name to variable type object

angr.sim_type.parse_types(defn, preprocess=True, predefined_types=None, arch=None)

Parse a series of C definitions, returns a mapping from type name to type object

angr.sim_type.parse_file(defn, preprocess=True, predefined_types=None, arch=None)

Parse a series of C definitions, returns a tuple of two type mappings, one for variable definitions and one for type definitions.

Parameters:

predefined_types (Dict[Any, SimType] | None) –

angr.sim_type.type_parser_singleton()

Return type:

Optional[CParser]

angr.sim_type.parse_type(defn, preprocess=True, predefined_types=None, arch=None)

Parse a simple type expression into a SimType

>>> parse_type('int *')

angr.sim_type.parse_type_with_name(defn, preprocess=True, predefined_types=None, arch=None)

Parse a simple type expression into a SimType, returning a tuple of the type object and any associated name that might be found in the place a name would go in a type declaration.

>>> parse_type_with_name('int *foo')

Parameters:

predefined_types (Dict[Any, SimType] | None) –

angr.sim_type.normalize_cpp_function_name(name)

Return type:

str

Parameters:

name (str) –

angr.sim_type.parse_cpp_file(cpp_decl, with_param_names=False)

Parameters:

with_param_names (bool) –

class angr.callable.Callable(project, addr, prototype=None, 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.

__init__(project, addr, prototype=None, concrete_only=False, perform_merge=True, base_state=None, toc=None, cc=None)

Parameters:

• project – The project to operate on

• addr – The address of the function to use

The following parameters are optional:

Parameters:

• prototype – The signature of the calls you would like to make. This really shouldn’t be optional.

• 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 :type state: :param state: The state to use to perform the call

perform_call(*args, prototype=None)

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.knowledge_base.KnowledgeBase(project, obj=None, name=None)

Bases: object

Represents a “model” of knowledge about an artifact.

Contains things like a CFG, data references, etc.

functions: FunctionManager

variables: VariableManager

structured_code: StructuredCodeManager

defs: KeyDefinitionManager

cfgs: CFGManager

types: TypesStore

propagations: PropagationManager

xrefs: XRefManager

__init__(project, obj=None, name=None)

property callgraph

property unresolved_indirect_jumps

property resolved_indirect_jumps

has_plugin(name)

get_plugin(name)

register_plugin(name, plugin)

release_plugin(name)

K = ~K

get_knowledge(requested_plugin_cls)

Type inference safe method to request a knowledge base plugin Explicitly passing the type of the requested plugin achieves two things: 1. Every location using this plugin can be easily found with an IDE by searching explicit references to the type 2. Basic type inference can deduce the result type and properly type check usages of it

If there isn’t already an instance of this class None will be returned to make it clear to the caller that there is no existing knowledge of this type yet. The code that initially creates this knowledge should use the register_plugin method to register the initial knowledge state :type requested_plugin_cls: Type[TypeVar(K, bound= KnowledgeBasePlugin)] :param requested_plugin_cls: :rtype: Optional[TypeVar(K, bound= KnowledgeBasePlugin)] :return: Instance of the requested plugin class or null if it is not a known plugin

Parameters:

requested_plugin_cls (Type[K]) –

Return type:

K | None

request_knowledge(requested_plugin_cls)

Return type:

TypeVar(K, bound= KnowledgeBasePlugin)

Parameters:

requested_plugin_cls (Type[K]) –

class angr.knowledge_plugins.patches.Patch(addr, new_bytes, comment=None)

Bases: object

Parameters:

comment (str | None) –

__init__(addr, new_bytes, comment=None)

Parameters:

comment (str | None) –

class angr.knowledge_plugins.patches.PatchManager(kb)

Bases: KnowledgeBasePlugin

A placeholder-style implementation for a binary patch manager. This class should be significantly changed in the future when all data about loaded binary objects are loaded into angr knowledge base from CLE. As of now, it only stores byte-level replacements. Other angr components may choose to use or not use information provided by this manager. In other words, it is not transparent.

Patches should not overlap, but it’s user’s responsibility to check for and avoid overlapping patches.

__init__(kb)

add_patch(addr, new_bytes, comment=None)

Parameters:

comment (str | None) –

add_patch_obj(patch)

Parameters:

patch (Patch) –

remove_patch(addr)

patch_addrs()

get_patch(addr)

Get patch at the given address.

Parameters:

addr (int) – The address of the patch.

Returns:

The patch if there is one starting at the address, or None if there isn’t any.

Return type:

Patch or None

get_all_patches(addr, size)

Retrieve all patches that cover a region specified by [addr, addr+size).

Parameters:

• addr (int) – The address of the beginning of the region.

• size (int) – Size of the region.

Returns:

A list of patches.

Return type:

list

keys()

items()

values()

copy()

static overlap(a0, a1, b0, b1)

apply_patches_to_binary(binary_bytes=None, patches=None)

Return type:

bytes

Parameters:

• binary_bytes (bytes | None) –

• patches (List[Patch] | None) –

static register_default(name, cls)

class angr.knowledge_plugins.plugin.KnowledgeBasePlugin

Bases: object

copy()

static register_default(name, cls)

class angr.knowledge_plugins.callsite_prototypes.CallsitePrototypes(kb)

Bases: KnowledgeBasePlugin

CallsitePrototypes manages callee prototypes at call sites.

__init__(kb)

set_prototype(callsite_block_addr, cc, prototype, manual=False)

Return type:

None

Parameters:

• callsite_block_addr (int) –

• cc (SimCC) –

• prototype (SimTypeFunction) –

• manual (bool) –

get_cc(callsite_block_addr)

Return type:

Optional[SimCC]

Parameters:

callsite_block_addr (int) –

get_prototype(callsite_block_addr)

Return type:

Optional[SimTypeFunction]

Parameters:

callsite_block_addr (int) –

get_prototype_type(callsite_block_addr)

Return type:

Optional[bool]

Parameters:

callsite_block_addr (int) –

has_prototype(callsite_block_addr)

Return type:

bool

Parameters:

callsite_block_addr (int) –

copy()

static register_default(name, cls)

class angr.knowledge_plugins.cfg.MemoryDataSort

Bases: object

Unspecified = None

Unknown = 'unknown'

Integer = 'integer'

PointerArray = 'pointer-array'

String = 'string'

UnicodeString = 'unicode'

SegmentBoundary = 'segment-boundary'

CodeReference = 'code reference'

GOTPLTEntry = 'GOT PLT Entry'

ELFHeader = 'elf-header'

FloatingPoint = 'fp'

class angr.knowledge_plugins.cfg.MemoryData(address, size, sort, pointer_addr=None, max_size=None)

Bases: Serializable

MemoryData describes the syntactic content of a single address of memory.

Parameters:

• address (int) –

• size (int) –

• sort (str | None) –

• pointer_addr (int | None) –

• max_size (int | None) –

__init__(address, size, sort, pointer_addr=None, max_size=None)

Parameters:

• address (int) –

• size (int) –

• sort (str | None) –

• pointer_addr (int | None) –

• max_size (int | None) –

addr: int

size: int

sort: Optional[str]

max_size: Optional[int]

pointer_addr: Optional[int]

content: Optional[bytes]

property address

copy()

Make a copy of the MemoryData.

Returns:

A copy of the MemoryData instance.

Return type:

MemoryData

fill_content(loader)

Load data to fill self.content.

Parameters:

loader – The project loader.

Returns:

None

serialize_to_cmessage()

Serialize the class object and returns a protobuf cmessage object.

Returns:

A protobuf cmessage object.

Return type:

protobuf.cmessage

classmethod parse_from_cmessage(cmsg, **kwargs)

Parse a protobuf cmessage and create a class object.

Parameters:

cmsg – The probobuf cmessage object.

Returns:

A unserialized class object.

Return type:

cls

classmethod parse(s, **kwargs)

Parse a bytes object and create a class object.

Parameters:

s (bytes) – A bytes object.

Returns:

A class object.

Return type:

cls

serialize()

Serialize the class object and returns a bytes object.

Returns:

A bytes object.

Return type:

bytes

class angr.knowledge_plugins.cfg.CFGNode(addr, size, cfg, simprocedure_name=None, no_ret=False, function_address=None, block_id=None, irsb=None, soot_block=None, instruction_addrs=None, thumb=False, byte_string=None, is_syscall=None, name=None)

Bases: Serializable

This class stands for each single node in CFG.

__init__(addr, size, cfg, simprocedure_name=None, no_ret=False, function_address=None, block_id=None, irsb=None, soot_block=None, instruction_addrs=None, thumb=False, byte_string=None, is_syscall=None, name=None)

Note: simprocedure_name is not used to recreate the SimProcedure object. It’s only there for better __repr__.

addr

size

simprocedure_name

no_ret

function_address

thumb

byte_string: Optional[bytes]

is_syscall

instruction_addrs

irsb

soot_block

has_return

block_id: Union[angr.analyses.cfg.cfg_job_base.BlockID, int]

property name

property successors

property predecessors

successors_and_jumpkinds(excluding_fakeret=True)

predecessors_and_jumpkinds(excluding_fakeret=True)

get_data_references(kb=None)

Get the known data references for this CFGNode via the knowledge base.

Parameters:

kb – Which knowledge base to use; uses the global KB by default if none is provided

Returns:

Generator yielding xrefs to this CFGNode’s block.

Return type:

iter

property accessed_data_references

Property providing a view of all the known data references for this CFGNode via the global knowledge base

Returns:

Generator yielding xrefs to this CFGNode’s block.

Return type:

iter

property is_simprocedure

property callstack_key

serialize_to_cmessage()

Serialize the class object and returns a protobuf cmessage object.

Returns:

A protobuf cmessage object.

Return type:

protobuf.cmessage

classmethod parse_from_cmessage(cmsg, cfg=None)

Parse a protobuf cmessage and create a class object.

Parameters:

cmsg – The probobuf cmessage object.

Returns:

A unserialized class object.

Return type:

cls

copy()

merge(other)

Merges this node with the other, returning a new node that spans the both.

to_codenode()

property block

syscall_name

classmethod parse(s, **kwargs)

Parse a bytes object and create a class object.

Parameters:

s (bytes) – A bytes object.

Returns:

A class object.

Return type:

cls

serialize()

Serialize the class object and returns a bytes object.

Returns:

A bytes object.

Return type:

bytes

class angr.knowledge_plugins.cfg.CFGENode(addr, size, cfg, simprocedure_name=None, no_ret=False, function_address=None, block_id=None, irsb=None, instruction_addrs=None, thumb=False, byte_string=None, is_syscall=None, name=None, input_state=None, final_states=None, syscall_name=None, looping_times=0, depth=None, callstack_key=None, creation_failure_info=None)

Bases: CFGNode

The CFGNode that is used in CFGEmulated.

Parameters:

• block_id (angr.analyses.cfg.cfg_job_base.BlockID | int) –

• byte_string (bytes | None) –

__init__(addr, size, cfg, simprocedure_name=None, no_ret=False, function_address=None, block_id=None, irsb=None, instruction_addrs=None, thumb=False, byte_string=None, is_syscall=None, name=None, input_state=None, final_states=None, syscall_name=None, looping_times=0, depth=None, callstack_key=None, creation_failure_info=None)

Note: simprocedure_name is not used to recreate the SimProcedure object. It’s only there for better __repr__.

input_state

syscall_name

looping_times

depth

creation_failure_info

final_states

return_target

syscall

property accessed_data_references

Property providing a view of all the known data references for this CFGNode via the global knowledge base

Returns:

Generator yielding xrefs to this CFGNode’s block.

Return type:

iter

addr

property block

block_id: Union[angr.analyses.cfg.cfg_job_base.BlockID, int]

byte_string: Optional[bytes]

function_address

get_data_references(kb=None)

Get the known data references for this CFGNode via the knowledge base.

Parameters:

kb – Which knowledge base to use; uses the global KB by default if none is provided

Returns:

Generator yielding xrefs to this CFGNode’s block.

Return type:

iter

has_return

instruction_addrs

irsb

property is_simprocedure

is_syscall

merge(other)

Merges this node with the other, returning a new node that spans the both.

property name

no_ret

classmethod parse(s, **kwargs)

Parse a bytes object and create a class object.

Parameters:

s (bytes) – A bytes object.

Returns:

A class object.

Return type:

cls

classmethod parse_from_cmessage(cmsg, cfg=None)

Parse a protobuf cmessage and create a class object.

Parameters:

cmsg – The probobuf cmessage object.

Returns:

A unserialized class object.

Return type:

cls

property predecessors

predecessors_and_jumpkinds(excluding_fakeret=True)

serialize()

Serialize the class object and returns a bytes object.

Returns:

A bytes object.

Return type:

bytes

serialize_to_cmessage()

Serialize the class object and returns a protobuf cmessage object.

Returns:

A protobuf cmessage object.

Return type:

protobuf.cmessage

simprocedure_name

size

soot_block

property successors

successors_and_jumpkinds(excluding_fakeret=True)

thumb

to_codenode()

property callstack_key

property creation_failed

downsize()

Drop saved states.

copy()

class angr.knowledge_plugins.cfg.IndirectJump(addr, ins_addr, func_addr, jumpkind, stmt_idx, resolved_targets=None, jumptable=False, jumptable_addr=None, jumptable_size=None, jumptable_entry_size=None, jumptable_entries=None, type_=255)

Bases: Serializable

Parameters:

• addr (int) –

• ins_addr (int) –

• func_addr (int) –

• jumpkind (str) –

• stmt_idx (int) –

• resolved_targets (List[int] | None) –

• jumptable (bool) –

• jumptable_addr (int | None) –

• jumptable_size (int | None) –

• jumptable_entry_size (int | None) –

• jumptable_entries (List[int] | None) –

• type_ (int | None) –

__init__(addr, ins_addr, func_addr, jumpkind, stmt_idx, resolved_targets=None, jumptable=False, jumptable_addr=None, jumptable_size=None, jumptable_entry_size=None, jumptable_entries=None, type_=255)

Parameters:

• addr (int) –

• ins_addr (int) –

• func_addr (int) –

• jumpkind (str) –

• stmt_idx (int) –

• resolved_targets (List[int] | None) –

• jumptable (bool) –

• jumptable_addr (int | None) –

• jumptable_size (int | None) –

• jumptable_entry_size (int | None) –

• jumptable_entries (List[int] | None) –

• type_ (int | None) –

addr

ins_addr

func_addr

jumpkind

stmt_idx

resolved_targets

jumptable

jumptable_addr

jumptable_size

jumptable_entry_size

jumptable_entries

type

classmethod parse(s, **kwargs)

Parse a bytes object and create a class object.

Parameters:

s (bytes) – A bytes object.

Returns:

A class object.

Return type:

cls

classmethod parse_from_cmessage(cmsg, **kwargs)

Parse a protobuf cmessage and create a class object.

Parameters:

cmsg – The probobuf cmessage object.

Returns:

A unserialized class object.

Return type:

cls

serialize()

Serialize the class object and returns a bytes object.

Returns:

A bytes object.

Return type:

bytes

serialize_to_cmessage()

Serialize the class object and returns a protobuf cmessage object.

Returns:

A protobuf cmessage object.

Return type:

protobuf.cmessage

class angr.knowledge_plugins.cfg.IndirectJumpType

Bases: object

Jumptable_AddressLoadedFromMemory = 0

Jumptable_AddressComputed = 1

Vtable = 3

Unknown = 255

class angr.knowledge_plugins.cfg.CFGModel(ident, cfg_manager=None, is_arm=False)

Bases: Serializable

This class describes a Control Flow Graph for a specific range of code.

__init__(ident, cfg_manager=None, is_arm=False)

ident

is_arm

graph

jump_tables: Dict[int, IndirectJump]

memory_data: Dict[int, MemoryData]

insn_addr_to_memory_data: Dict[int, MemoryData]

normalized

property project

serialize_to_cmessage()

Serialize the class object and returns a protobuf cmessage object.

Returns:

A protobuf cmessage object.

Return type:

protobuf.cmessage

classmethod parse_from_cmessage(cmsg, cfg_manager=None, loader=None)

Parse a protobuf cmessage and create a class object.

Parameters:

cmsg – The probobuf cmessage object.

Returns:

A unserialized class object.

Return type:

cls

copy()

add_node(block_id, node)

Return type:

None

Parameters:

• block_id (int) –

• node (CFGNode) –

remove_node(block_id, node)

Remove the given CFGNode instance. Note that this method does not remove the node from the graph.

Parameters:

• block_id (int) – The Unique ID of the CFGNode.

• node (CFGNode) – The CFGNode instance to remove.

Return type:

None

Returns:

None

get_node(block_id)

Get a single node from node key.

Parameters:

block_id (BlockID) – Block ID of the node.

Returns:

The CFGNode

Return type:

CFGNode

get_any_node(addr, is_syscall=None, anyaddr=False, force_fastpath=False)

Get an arbitrary CFGNode (without considering their contexts) from our graph.

Parameters:

• addr (int) – Address of the beginning of the basic block. Set anyaddr to True to support arbitrary address.

• is_syscall (Optional[bool]) – Whether you want to get the syscall node or any other node. This is due to the fact that syscall SimProcedures have the same address as the targer it returns to. None means get either, True means get a syscall node, False means get something that isn’t a syscall node.

• anyaddr (bool) – If anyaddr is True, then addr doesn’t have to be the beginning address of a basic block. By default the entire graph.nodes() will be iterated, and the first node containing the specific address is returned, which can be slow.

• force_fastpath (bool) – If force_fastpath is True, it will only perform a dict lookup in the _nodes_by_addr dict.

Return type:

Optional[CFGNode]

Returns:

A CFGNode if there is any that satisfies given conditions, or None otherwise

get_all_nodes(addr, is_syscall=None, anyaddr=False)

Get all CFGNodes whose address is the specified one.

Parameters:

• addr (int) – Address of the node

• is_syscall (Optional[bool]) – True returns the syscall node, False returns the normal CFGNode, None returns both

• anyaddr (bool) –

Return type:

List[CFGNode]

Returns:

all CFGNodes

nodes()

An iterator of all nodes in the graph.

Returns:

The iterator.

Return type:

iterator

get_predecessors(cfgnode, excluding_fakeret=True, jumpkind=None)

Get predecessors of a node in the control flow graph.

Parameters:

• cfgnode (CFGNode) – The node.

• excluding_fakeret (bool) – True if you want to exclude all predecessors that is connected to the node with a fakeret edge.

• jumpkind (Optional[str]) – Only return predecessors with the specified jumpkind. This argument will be ignored if set to None.

Return type:

List[CFGNode]

Returns:

A list of predecessors

get_successors(node, excluding_fakeret=True, jumpkind=None)

Get successors of a node in the control flow graph.

Parameters:

• node (CFGNode) – The node.

• excluding_fakeret (bool) – True if you want to exclude all successors that is connected to the node with a fakeret edge.

• jumpkind (str | None) – Only return successors with the specified jumpkind. This argument will be ignored if set to None.

• jumpkind –

Returns:

A list of successors

Return type:

list

get_successors_and_jumpkinds(node, excluding_fakeret=True)

Get a list of tuples where the first element is the successor of the CFG node and the second element is the jumpkind of the successor.

Parameters:

• node (CFGNode) – The node.

• excluding_fakeret (bool) – True if you want to exclude all successors that are fall-through successors.

Returns:

A list of successors and their corresponding jumpkinds.

Return type:

list

get_successors_and_jumpkind(node, excluding_fakeret=True)

Get a list of tuples where the first element is the successor of the CFG node and the second element is the jumpkind of the successor.

Parameters:

• node (CFGNode) – The node.

• excluding_fakeret (bool) – True if you want to exclude all successors that are fall-through successors.

Returns:

A list of successors and their corresponding jumpkinds.

Return type:

list

get_predecessors_and_jumpkinds(node, excluding_fakeret=True)

Get a list of tuples where the first element is the predecessor of the CFG node and the second element is the jumpkind of the predecessor.

Parameters:

• node (CFGNode) – The node.

• excluding_fakeret (bool) – True if you want to exclude all predecessors that are fall-through predecessors.

Return type:

List[Tuple[CFGNode, str]]

Returns:

A list of predecessors and their corresponding jumpkinds.

get_predecessors_and_jumpkind(node, excluding_fakeret=True)

Get a list of tuples where the first element is the predecessor of the CFG node and the second element is the jumpkind of the predecessor.

Parameters:

• node (CFGNode) – The node.

• excluding_fakeret (bool) – True if you want to exclude all predecessors that are fall-through predecessors.

Return type:

List[Tuple[CFGNode, str]]

Returns:

A list of predecessors and their corresponding jumpkinds.

get_all_predecessors(cfgnode, depth_limit=None)

Get all predecessors of a specific node on the control flow graph.

Parameters:

• cfgnode (CFGNode) – The CFGNode object

• depth_limit (int) – Optional depth limit for the depth-first search

Returns:

A list of predecessors in the CFG

Return type:

list

get_all_successors(cfgnode, depth_limit=None)

Get all successors of a specific node on the control flow graph.

Parameters:

• cfgnode (CFGNode) – The CFGNode object

• depth_limit (int) – Optional depth limit for the depth-first search

Returns:

A list of successors in the CFG

Return type:

list

get_branching_nodes()

Returns all nodes that has an out degree >= 2

get_exit_stmt_idx(src_block, dst_block)

Get the corresponding exit statement ID for control flow to reach destination block from source block. The exit statement ID was put on the edge when creating the CFG. Note that there must be a direct edge between the two blocks, otherwise an exception will be raised.

Returns:

The exit statement ID

add_memory_data(data_addr, data_type, data_size=None)

Add a MemoryData entry to self.memory_data.

Parameters:

• data_addr (int) – Address of the data

• data_type (Optional[MemoryDataSort]) – Type of the memory data

• data_size (Optional[int]) – Size of the memory data, or None if unknown for now.

Return type:

bool

Returns:

True if a new memory data entry is added, False otherwise.

tidy_data_references(memory_data_addrs=None, exec_mem_regions=None, xrefs=None, seg_list=None, data_type_guessing_handlers=None)

Go through all data references (or the ones as specified by memory_data_addrs) and determine their sizes and types if possible.

Parameters:

• memory_data_addrs (Optional[List[int]]) – A list of addresses of memory data, or None if tidying all known memory data entries.

• exec_mem_regions (Optional[List[Tuple[int, int]]]) – A list of start and end addresses of executable memory regions.

• seg_list (Optional[SegmentList]) – The segment list that CFGFast uses during CFG recovery.

• data_type_guessing_handlers (Optional[List[Callable]]) – A list of Python functions that will guess data types. They will be called in sequence to determine data types for memory data whose type is unknown.

• xrefs (XRefManager | None) –

Return type:

bool

Returns:

True if new data entries are found, False otherwise.

classmethod parse(s, **kwargs)

Parse a bytes object and create a class object.

Parameters:

s (bytes) – A bytes object.

Returns:

A class object.

Return type:

cls

serialize()

Serialize the class object and returns a bytes object.

Returns:

A bytes object.

Return type:

bytes

class angr.knowledge_plugins.cfg.CFGManager(kb)

Bases: KnowledgeBasePlugin

__init__(kb)

new_model(prefix)

copy()

get_most_accurate()

Return type:

Optional[CFGModel]

Returns:

The most accurate CFG present in the CFGManager, or None if it does not hold any.

static register_default(name, cls)

class angr.knowledge_plugins.cfg.cfg_model.CFGModel(ident, cfg_manager=None, is_arm=False)

Bases: Serializable

This class describes a Control Flow Graph for a specific range of code.

__init__(ident, cfg_manager=None, is_arm=False)

ident

is_arm

graph

jump_tables: Dict[int, IndirectJump]

memory_data: Dict[int, MemoryData]

insn_addr_to_memory_data: Dict[int, MemoryData]

normalized

property project

serialize_to_cmessage()

Serialize the class object and returns a protobuf cmessage object.

Returns:

A protobuf cmessage object.

Return type:

protobuf.cmessage

classmethod parse_from_cmessage(cmsg, cfg_manager=None, loader=None)

Parse a protobuf cmessage and create a class object.

Parameters:

cmsg – The probobuf cmessage object.

Returns:

A unserialized class object.

Return type:

cls

copy()

add_node(block_id, node)

Return type:

None

Parameters:

• block_id (int) –

• node (CFGNode) –

remove_node(block_id, node)

Remove the given CFGNode instance. Note that this method does not remove the node from the graph.

Parameters:

• block_id (int) – The Unique ID of the CFGNode.

• node (CFGNode) – The CFGNode instance to remove.

Return type:

None

Returns:

None

get_node(block_id)

Get a single node from node key.

Parameters:

block_id (BlockID) – Block ID of the node.

Returns:

The CFGNode

Return type:

CFGNode

get_any_node(addr, is_syscall=None, anyaddr=False, force_fastpath=False)

Get an arbitrary CFGNode (without considering their contexts) from our graph.

Parameters:

• addr (int) – Address of the beginning of the basic block. Set anyaddr to True to support arbitrary address.

• is_syscall (Optional[bool]) – Whether you want to get the syscall node or any other node. This is due to the fact that syscall SimProcedures have the same address as the targer it returns to. None means get either, True means get a syscall node, False means get something that isn’t a syscall node.

• anyaddr (bool) – If anyaddr is True, then addr doesn’t have to be the beginning address of a basic block. By default the entire graph.nodes() will be iterated, and the first node containing the specific address is returned, which can be slow.

• force_fastpath (bool) – If force_fastpath is True, it will only perform a dict lookup in the _nodes_by_addr dict.

Return type:

Optional[CFGNode]

Returns:

A CFGNode if there is any that satisfies given conditions, or None otherwise

get_all_nodes(addr, is_syscall=None, anyaddr=False)

Get all CFGNodes whose address is the specified one.

Parameters:

• addr (int) – Address of the node

• is_syscall (Optional[bool]) – True returns the syscall node, False returns the normal CFGNode, None returns both

• anyaddr (bool) –

Return type:

List[CFGNode]

Returns:

all CFGNodes

nodes()

An iterator of all nodes in the graph.

Returns:

The iterator.

Return type:

iterator

get_predecessors(cfgnode, excluding_fakeret=True, jumpkind=None)

Get predecessors of a node in the control flow graph.

Parameters:

• cfgnode (CFGNode) – The node.

• excluding_fakeret (bool) – True if you want to exclude all predecessors that is connected to the node with a fakeret edge.

• jumpkind (Optional[str]) – Only return predecessors with the specified jumpkind. This argument will be ignored if set to None.

Return type:

List[CFGNode]

Returns:

A list of predecessors

get_successors(node, excluding_fakeret=True, jumpkind=None)

Get successors of a node in the control flow graph.

Parameters:

• node (CFGNode) – The node.

• excluding_fakeret (bool) – True if you want to exclude all successors that is connected to the node with a fakeret edge.

• jumpkind (str | None) – Only return successors with the specified jumpkind. This argument will be ignored if set to None.

• jumpkind –

Returns:

A list of successors

Return type:

list

get_successors_and_jumpkinds(node, excluding_fakeret=True)

Get a list of tuples where the first element is the successor of the CFG node and the second element is the jumpkind of the successor.

Parameters:

• node (CFGNode) – The node.

• excluding_fakeret (bool) – True if you want to exclude all successors that are fall-through successors.

Returns:

A list of successors and their corresponding jumpkinds.

Return type:

list

get_successors_and_jumpkind(node, excluding_fakeret=True)

Get a list of tuples where the first element is the successor of the CFG node and the second element is the jumpkind of the successor.

Parameters:

• node (CFGNode) – The node.

• excluding_fakeret (bool) – True if you want to exclude all successors that are fall-through successors.

Returns:

A list of successors and their corresponding jumpkinds.

Return type:

list

get_predecessors_and_jumpkinds(node, excluding_fakeret=True)

Get a list of tuples where the first element is the predecessor of the CFG node and the second element is the jumpkind of the predecessor.

Parameters:

• node (CFGNode) – The node.

• excluding_fakeret (bool) – True if you want to exclude all predecessors that are fall-through predecessors.

Return type:

List[Tuple[CFGNode, str]]

Returns:

A list of predecessors and their corresponding jumpkinds.

get_predecessors_and_jumpkind(node, excluding_fakeret=True)

Get a list of tuples where the first element is the predecessor of the CFG node and the second element is the jumpkind of the predecessor.

Parameters:

• node (CFGNode) – The node.

• excluding_fakeret (bool) – True if you want to exclude all predecessors that are fall-through predecessors.

Return type:

List[Tuple[CFGNode, str]]

Returns:

A list of predecessors and their corresponding jumpkinds.

get_all_predecessors(cfgnode, depth_limit=None)

Get all predecessors of a specific node on the control flow graph.

Parameters:

• cfgnode (CFGNode) – The CFGNode object

• depth_limit (int) – Optional depth limit for the depth-first search

Returns:

A list of predecessors in the CFG

Return type:

list

get_all_successors(cfgnode, depth_limit=None)

Get all successors of a specific node on the control flow graph.

Parameters:

• cfgnode (CFGNode) – The CFGNode object

• depth_limit (int) – Optional depth limit for the depth-first search

Returns:

A list of successors in the CFG

Return type:

list

get_branching_nodes()

Returns all nodes that has an out degree >= 2

get_exit_stmt_idx(src_block, dst_block)

Get the corresponding exit statement ID for control flow to reach destination block from source block. The exit statement ID was put on the edge when creating the CFG. Note that there must be a direct edge between the two blocks, otherwise an exception will be raised.

Returns:

The exit statement ID

add_memory_data(data_addr, data_type, data_size=None)

Add a MemoryData entry to self.memory_data.

Parameters:

• data_addr (int) – Address of the data

• data_type (Optional[MemoryDataSort]) – Type of the memory data

• data_size (Optional[int]) – Size of the memory data, or None if unknown for now.

Return type:

bool

Returns:

True if a new memory data entry is added, False otherwise.

tidy_data_references(memory_data_addrs=None, exec_mem_regions=None, xrefs=None, seg_list=None, data_type_guessing_handlers=None)

Go through all data references (or the ones as specified by memory_data_addrs) and determine their sizes and types if possible.

Parameters:

• memory_data_addrs (Optional[List[int]]) – A list of addresses of memory data, or None if tidying all known memory data entries.

• exec_mem_regions (Optional[List[Tuple[int, int]]]) – A list of start and end addresses of executable memory regions.

• seg_list (Optional[SegmentList]) – The segment list that CFGFast uses during CFG recovery.

• data_type_guessing_handlers (Optional[List[Callable]]) – A list of Python functions that will guess data types. They will be called in sequence to determine data types for memory data whose type is unknown.

• xrefs (XRefManager | None) –

Return type:

bool

Returns:

True if new data entries are found, False otherwise.

classmethod parse(s, **kwargs)

Parse a bytes object and create a class object.

Parameters:

s (bytes) – A bytes object.

Returns:

A class object.

Return type:

cls

serialize()

Serialize the class object and returns a bytes object.

Returns:

A bytes object.

Return type:

bytes

class angr.knowledge_plugins.cfg.memory_data.MemoryDataSort

Bases: object

Unspecified = None

Unknown = 'unknown'

Integer = 'integer'

PointerArray = 'pointer-array'

String = 'string'

UnicodeString = 'unicode'

SegmentBoundary = 'segment-boundary'

CodeReference = 'code reference'

GOTPLTEntry = 'GOT PLT Entry'

ELFHeader = 'elf-header'

FloatingPoint = 'fp'

class angr.knowledge_plugins.cfg.memory_data.MemoryData(address, size, sort, pointer_addr=None, max_size=None)

Bases: Serializable

MemoryData describes the syntactic content of a single address of memory.

Parameters:

• address (int) –

• size (int) –

• sort (str | None) –

• pointer_addr (int | None) –

• max_size (int | None) –

__init__(address, size, sort, pointer_addr=None, max_size=None)

Parameters:

• address (int) –

• size (int) –

• sort (str | None) –

• pointer_addr (int | None) –

• max_size (int | None) –

addr: int

size: int

sort: Optional[str]

max_size: Optional[int]

pointer_addr: Optional[int]

content: Optional[bytes]

property address

copy()

Make a copy of the MemoryData.

Returns:

A copy of the MemoryData instance.

Return type:

MemoryData

fill_content(loader)

Load data to fill self.content.

Parameters:

loader – The project loader.

Returns:

None

serialize_to_cmessage()

Serialize the class object and returns a protobuf cmessage object.

Returns:

A protobuf cmessage object.

Return type:

protobuf.cmessage

classmethod parse_from_cmessage(cmsg, **kwargs)

Parse a protobuf cmessage and create a class object.

Parameters:

cmsg – The probobuf cmessage object.

Returns:

A unserialized class object.

Return type:

cls

classmethod parse(s, **kwargs)

Parse a bytes object and create a class object.

Parameters:

s (bytes) – A bytes object.

Returns:

A class object.

Return type:

cls

serialize()

Serialize the class object and returns a bytes object.

Returns:

A bytes object.

Return type:

bytes

class angr.knowledge_plugins.cfg.cfg_manager.CFGManager(kb)

Bases: KnowledgeBasePlugin

__init__(kb)

new_model(prefix)

copy()

get_most_accurate()

Return type:

Optional[CFGModel]

Returns:

The most accurate CFG present in the CFGManager, or None if it does not hold any.

static register_default(name, cls)

class angr.knowledge_plugins.cfg.cfg_node.CFGNodeCreationFailure(exc_info=None, to_copy=None)

Bases: object

This class contains additional information for whenever creating a CFGNode failed. It includes a full traceback and the exception messages.

__init__(exc_info=None, to_copy=None)

short_reason

long_reason

traceback

class angr.knowledge_plugins.cfg.cfg_node.CFGNode(addr, size, cfg, simprocedure_name=None, no_ret=False, function_address=None, block_id=None, irsb=None, soot_block=None, instruction_addrs=None, thumb=False, byte_string=None, is_syscall=None, name=None)

Bases: Serializable

This class stands for each single node in CFG.

Parameters:

• block_id (angr.analyses.cfg.cfg_job_base.BlockID | int) –

• byte_string (bytes | None) –

__init__(addr, size, cfg, simprocedure_name=None, no_ret=False, function_address=None, block_id=None, irsb=None, soot_block=None, instruction_addrs=None, thumb=False, byte_string=None, is_syscall=None, name=None)

Note: simprocedure_name is not used to recreate the SimProcedure object. It’s only there for better __repr__.

addr

size

simprocedure_name

no_ret

function_address

thumb

byte_string: Optional[bytes]

is_syscall

instruction_addrs

irsb

soot_block

has_return

block_id: Union[angr.analyses.cfg.cfg_job_base.BlockID, int]

property name

property successors

property predecessors

successors_and_jumpkinds(excluding_fakeret=True)

predecessors_and_jumpkinds(excluding_fakeret=True)

get_data_references(kb=None)

Get the known data references for this CFGNode via the knowledge base.

Parameters:

kb – Which knowledge base to use; uses the global KB by default if none is provided

Returns:

Generator yielding xrefs to this CFGNode’s block.

Return type:

iter

property accessed_data_references

Property providing a view of all the known data references for this CFGNode via the global knowledge base

Returns:

Generator yielding xrefs to this CFGNode’s block.

Return type:

iter

property is_simprocedure

property callstack_key

serialize_to_cmessage()

Serialize the class object and returns a protobuf cmessage object.

Returns:

A protobuf cmessage object.

Return type:

protobuf.cmessage

classmethod parse_from_cmessage(cmsg, cfg=None)

Parse a protobuf cmessage and create a class object.

Parameters:

cmsg – The probobuf cmessage object.

Returns:

A unserialized class object.

Return type:

cls

copy()

merge(other)

Merges this node with the other, returning a new node that spans the both.

to_codenode()

property block

syscall_name

classmethod parse(s, **kwargs)

Parse a bytes object and create a class object.

Parameters:

s (bytes) – A bytes object.

Returns:

A class object.

Return type:

cls

serialize()

Serialize the class object and returns a bytes object.

Returns:

A bytes object.

Return type:

bytes

class angr.knowledge_plugins.cfg.cfg_node.CFGENode(addr, size, cfg, simprocedure_name=None, no_ret=False, function_address=None, block_id=None, irsb=None, instruction_addrs=None, thumb=False, byte_string=None, is_syscall=None, name=None, input_state=None, final_states=None, syscall_name=None, looping_times=0, depth=None, callstack_key=None, creation_failure_info=None)

Bases: CFGNode

The CFGNode that is used in CFGEmulated.

Parameters:

• block_id (angr.analyses.cfg.cfg_job_base.BlockID | int) –

• byte_string (bytes | None) –

__init__(addr, size, cfg, simprocedure_name=None, no_ret=False, function_address=None, block_id=None, irsb=None, instruction_addrs=None, thumb=False, byte_string=None, is_syscall=None, name=None, input_state=None, final_states=None, syscall_name=None, looping_times=0, depth=None, callstack_key=None, creation_failure_info=None)

Note: simprocedure_name is not used to recreate the SimProcedure object. It’s only there for better __repr__.

input_state

syscall_name

looping_times

depth

creation_failure_info

final_states

return_target

syscall

property accessed_data_references

Property providing a view of all the known data references for this CFGNode via the global knowledge base

Returns:

Generator yielding xrefs to this CFGNode’s block.

Return type:

iter

addr

property block

block_id: Union[angr.analyses.cfg.cfg_job_base.BlockID, int]

byte_string: Optional[bytes]

function_address

get_data_references(kb=None)

Get the known data references for this CFGNode via the knowledge base.

Parameters:

kb – Which knowledge base to use; uses the global KB by default if none is provided

Returns:

Generator yielding xrefs to this CFGNode’s block.

Return type:

iter

has_return

instruction_addrs

irsb

property is_simprocedure

is_syscall

merge(other)

Merges this node with the other, returning a new node that spans the both.

property name

no_ret

classmethod parse(s, **kwargs)

Parse a bytes object and create a class object.

Parameters:

s (bytes) – A bytes object.

Returns:

A class object.

Return type:

cls

classmethod parse_from_cmessage(cmsg, cfg=None)

Parse a protobuf cmessage and create a class object.

Parameters:

cmsg – The probobuf cmessage object.

Returns:

A unserialized class object.

Return type:

cls

property predecessors

predecessors_and_jumpkinds(excluding_fakeret=True)

serialize()

Serialize the class object and returns a bytes object.

Returns:

A bytes object.

Return type:

bytes

serialize_to_cmessage()

Serialize the class object and returns a protobuf cmessage object.

Returns:

A protobuf cmessage object.

Return type:

protobuf.cmessage

simprocedure_name

size

soot_block

property successors

successors_and_jumpkinds(excluding_fakeret=True)

thumb

to_codenode()

property callstack_key

property creation_failed

downsize()

Drop saved states.

copy()

class angr.knowledge_plugins.cfg.indirect_jump.IndirectJumpType

Bases: object

Jumptable_AddressLoadedFromMemory = 0

Jumptable_AddressComputed = 1

Vtable = 3

Unknown = 255

class angr.knowledge_plugins.cfg.indirect_jump.IndirectJump(addr, ins_addr, func_addr, jumpkind, stmt_idx, resolved_targets=None, jumptable=False, jumptable_addr=None, jumptable_size=None, jumptable_entry_size=None, jumptable_entries=None, type_=255)

Bases: Serializable

Parameters:

• addr (int) –

• ins_addr (int) –

• func_addr (int) –

• jumpkind (str) –

• stmt_idx (int) –

• resolved_targets (List[int] | None) –

• jumptable (bool) –

• jumptable_addr (int | None) –

• jumptable_size (int | None) –

• jumptable_entry_size (int | None) –

• jumptable_entries (List[int] | None) –

• type_ (int | None) –

__init__(addr, ins_addr, func_addr, jumpkind, stmt_idx, resolved_targets=None, jumptable=False, jumptable_addr=None, jumptable_size=None, jumptable_entry_size=None, jumptable_entries=None, type_=255)

Parameters:

• addr (int) –

• ins_addr (int) –

• func_addr (int) –

• jumpkind (str) –

• stmt_idx (int) –

• resolved_targets (List[int] | None) –

• jumptable (bool) –

• jumptable_addr (int | None) –

• jumptable_size (int | None) –

• jumptable_entry_size (int | None) –

• jumptable_entries (List[int] | None) –

• type_ (int | None) –

addr

ins_addr

func_addr

jumpkind

stmt_idx

resolved_targets

jumptable

jumptable_addr

jumptable_size

jumptable_entry_size

jumptable_entries

type

classmethod parse(s, **kwargs)

Parse a bytes object and create a class object.

Parameters:

s (bytes) – A bytes object.

Returns:

A class object.

Return type:

cls

classmethod parse_from_cmessage(cmsg, **kwargs)

Parse a protobuf cmessage and create a class object.

Parameters:

cmsg – The probobuf cmessage object.

Returns:

A unserialized class object.

Return type:

cls

serialize()

Serialize the class object and returns a bytes object.

Returns:

A bytes object.

Return type:

bytes

serialize_to_cmessage()

Serialize the class object and returns a protobuf cmessage object.

Returns:

A protobuf cmessage object.

Return type:

protobuf.cmessage

class angr.knowledge_plugins.types.TypesStore(kb)

Bases: KnowledgeBasePlugin, UserDict

A kb plugin that stores a mapping from name to TypeRef. It will return types from angr.sim_type.ALL_TYPES as a default.

__init__(kb)

copy()

iter_own()

Iterate over all the names which are stored in this object - i.e. values() without ALL_TYPES

rename(old, new)

unique_type_name()

Return type:

str

clear() → None.  Remove all items from D.

classmethod fromkeys(iterable, value=None)

get(k[, d]) → D[k] if k in D, else d.  d defaults to None.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

static register_default(name, cls)

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

update([E, ]**F) → None.  Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → an object providing a view on D's values

class angr.knowledge_plugins.comments.Comments(kb)

Bases: KnowledgeBasePlugin, dict

__init__(kb)

copy() → a shallow copy of D

clear() → None.  Remove all items from D.

fromkeys(value=None, /)

Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)

Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

static register_default(name, cls)

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None.  Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values

class angr.knowledge_plugins.data.Data(kb)

Bases: KnowledgeBasePlugin

__init__(kb)

copy()

static register_default(name, cls)

class angr.knowledge_plugins.indirect_jumps.IndirectJumps(kb)

Bases: KnowledgeBasePlugin, dict

__init__(kb)

copy() → a shallow copy of D

update_resolved_addrs(indirect_address, resolved_addresses)

Parameters:

• indirect_address (int) –

• resolved_addresses (List[int]) –

clear() → None.  Remove all items from D.

fromkeys(value=None, /)

Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)

Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

static register_default(name, cls)

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None.  Update D from dict/iterable E and F.

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values

class angr.knowledge_plugins.labels.Labels(kb)

Bases: KnowledgeBasePlugin

__init__(kb)

items()

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

get_unique_label(label)

Get a unique label name from the given label name.

Parameters:

label (str) – The desired label name.

Returns:

A unique label name.

static register_default(name, cls)

class angr.knowledge_plugins.functions.function_manager.FunctionDict(backref, *args, **kwargs)

Bases: SortedDict

FunctionDict is a dict where the keys are function starting addresses and map to the associated Function.

__init__(backref, *args, **kwargs)

Initialize sorted dict instance.

Optional key-function argument defines a callable that, like the key argument to the built-in sorted function, extracts a comparison key from each dictionary key. If no function is specified, the default compares the dictionary keys directly. The key-function argument must be provided as a positional argument and must come before all other arguments.

Optional iterable argument provides an initial sequence of pairs to initialize the sorted dict. Each pair in the sequence defines the key and corresponding value. If a key is seen more than once, the last value associated with it is stored in the new sorted dict.

Optional mapping argument provides an initial mapping of items to initialize the sorted dict.

If keyword arguments are given, the keywords themselves, with their associated values, are added as items to the dictionary. If a key is specified both in the positional argument and as a keyword argument, the value associated with the keyword is stored in the sorted dict.

Sorted dict keys must be hashable, per the requirement for Python’s dictionaries. Keys (or the result of the key-function) must also be comparable, per the requirement for sorted lists.

>>> d = {'alpha': 1, 'beta': 2}
>>> SortedDict([('alpha', 1), ('beta', 2)]) == d
True
>>> SortedDict({'alpha': 1, 'beta': 2}) == d
True
>>> SortedDict(alpha=1, beta=2) == d
True

get(addr)

Return the value for key if key is in the dictionary, else default.

floor_addr(addr)

ceiling_addr(addr)

clear()

Remove all items from sorted dict.

Runtime complexity: O(n)

copy()

Return a shallow copy of the sorted dict.

Runtime complexity: O(n)

Returns:

new sorted dict

classmethod fromkeys(iterable, value=None)

Return a new sorted dict initailized from iterable and value.

Items in the sorted dict have keys from iterable and values equal to value.

Runtime complexity: O(n*log(n))

Returns:

new sorted dict

property iloc

Cached reference of sorted keys view.

Deprecated in version 2 of Sorted Containers. Use SortedDict.keys() instead.

items()

Return new sorted items view of the sorted dict’s items.

See SortedItemsView for details.

Returns:

new sorted items view

property key

Function used to extract comparison key from keys.

Sorted dict compares keys directly when the key function is none.

keys()

Return new sorted keys view of the sorted dict’s keys.

See SortedKeysView for details.

Returns:

new sorted keys view

peekitem(index=-1)

Return (key, value) pair at index in sorted dict.

Optional argument index defaults to -1, the last item in the sorted dict. Specify index=0 for the first item in the sorted dict.

Unlike SortedDict.popitem(), the sorted dict is not modified.

If the index is out of range, raises IndexError.

Runtime complexity: O(log(n))

>>> sd = SortedDict({'a': 1, 'b': 2, 'c': 3})
>>> sd.peekitem()
('c', 3)
>>> sd.peekitem(0)
('a', 1)
>>> sd.peekitem(100)
Traceback (most recent call last):
  ...
IndexError: list index out of range

Parameters:

index (int) – index of item (default -1)

Returns:

key and value pair

Raises:

IndexError – if index out of range

pop(key, default=<not-given>)

Remove and return value for item identified by key.

If the key is not found then return default if given. If default is not given then raise KeyError.

Runtime complexity: O(log(n)) – approximate.

>>> sd = SortedDict({'a': 1, 'b': 2, 'c': 3})
>>> sd.pop('c')
3
>>> sd.pop('z', 26)
26
>>> sd.pop('y')
Traceback (most recent call last):
  ...
KeyError: 'y'

Parameters:

• key – key for item

• default – default value if key not found (optional)

Returns:

value for item

Raises:

KeyError – if key not found and default not given

popitem(index=-1)

Remove and return (key, value) pair at index from sorted dict.

Optional argument index defaults to -1, the last item in the sorted dict. Specify index=0 for the first item in the sorted dict.

If the sorted dict is empty, raises KeyError.

If the index is out of range, raises IndexError.

Runtime complexity: O(log(n))

>>> sd = SortedDict({'a': 1, 'b': 2, 'c': 3})
>>> sd.popitem()
('c', 3)
>>> sd.popitem(0)
('a', 1)
>>> sd.popitem(100)
Traceback (most recent call last):
  ...
IndexError: list index out of range

Parameters:

index (int) – index of item (default -1)

Returns:

key and value pair

Raises:

• KeyError – if sorted dict is empty

• IndexError – if index out of range

setdefault(key, default=None)

Return value for item identified by key in sorted dict.

If key is in the sorted dict then return its value. If key is not in the sorted dict then insert key with value default and return default.

Optional argument default defaults to none.

Runtime complexity: O(log(n)) – approximate.

>>> sd = SortedDict()
>>> sd.setdefault('a', 1)
1
>>> sd.setdefault('a', 10)
1
>>> sd
SortedDict({'a': 1})

Parameters:

• key – key for item

• default – value for item (default None)

Returns:

value for item identified by key

update(*args, **kwargs)

Update sorted dict with items from args and kwargs.

Overwrites existing items.

Optional arguments args and kwargs may be a mapping, an iterable of pairs or keyword arguments. See SortedDict.__init__() for details.

Parameters:

• args – mapping or iterable of pairs

• kwargs – keyword arguments mapping

values()

Return new sorted values view of the sorted dict’s values.

See SortedValuesView for details.

Returns:

new sorted values view

class angr.knowledge_plugins.functions.function_manager.FunctionManager(kb)

Bases: KnowledgeBasePlugin, Mapping

This is a function boundaries management tool. It takes in intermediate results during CFG generation, and manages a function map of the binary.

__init__(kb)

copy()

clear()

get_by_addr(addr)

Return type:

Function

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.

• plt (bool or None) – 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_')

rebuild_callgraph()

get(k[, d]) → D[k] if k in D, else d.  d defaults to None.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

static register_default(name, cls)

values() → an object providing a view on D's values

class angr.knowledge_plugins.functions.function.Function(function_manager, addr, name=None, syscall=None, is_simprocedure=None, binary_name=None, is_plt=None, returning=None, alignment=False)

Bases: Serializable

A representation of a function and various information about it.

Parameters:

• is_simprocedure (bool | None) –

• is_plt (bool | None) –

__init__(function_manager, addr, name=None, syscall=None, is_simprocedure=None, binary_name=None, is_plt=None, returning=None, alignment=False)

Function constructor. If the optional parameters are not provided, they will be automatically determined upon the creation of a Function object.

Parameters:

• addr – The address of the function.

• is_simprocedure (bool | None) –

• is_plt (bool | None) –

The following parameters are optional.

Parameters:

• name (str) – The name of the function.

• syscall (bool) – Whether this function is a syscall or not.

• is_simprocedure (bool) – Whether this function is a SimProcedure or not.

• binary_name (str) – Name of the binary where this function is.

• is_plt (bool) – If this function is a PLT entry.

• returning (bool) – If this function returns.

• alignment (bool) – If this function acts as an alignment filler. Such functions usually only contain nops.

transition_graph

normalized

addr

startpoint

is_alignment

bp_on_stack

retaddr_on_stack

sp_delta

prototype: Optional[SimTypeFunction]

is_prototype_guessed: bool

prepared_registers

prepared_stack_variables

registers_read_afterwards

info

tags

ran_cca

is_syscall

is_simprocedure

is_plt

is_default_name

from_signature

binary_name

calling_convention: Optional[SimCC]

property alignment

property name

property project

property returning

property blocks

An iterator of all local blocks in the current function.

Returns:

angr.lifter.Block instances.

property block_addrs

An iterator of all local block addresses in the current function.

Returns:

block addresses.

property 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

get_block(addr, size=None, byte_string=None)

Getting a block out of the current function.

Parameters:

• addr (int) – The address of the block.

• size (int) – The size of the block. This is optional. If not provided, angr will load

• byte_string (Optional[bytes]) –

Returns:

get_block_size(addr)

Return type:

Optional[int]

Parameters:

addr (int) –

property nodes: Generator[CodeNode, None, None]

get_node(addr)

property has_unresolved_jumps

property has_unresolved_calls

property operations

All of the operations that are done by this functions.

property code_constants

All of the constants that are used by this functions’s code.

serialize_to_cmessage()

Serialize the class object and returns a protobuf cmessage object.

Returns:

A protobuf cmessage object.

Return type:

protobuf.cmessage

classmethod parse_from_cmessage(cmsg, **kwargs)

Parameters:

cmsg –

Return Function:

The function instantiated out of the cmsg data.

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.

property 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

property num_arguments

property endpoints

property endpoints_with_type

property ret_sites

property jumpout_sites

property retout_sites

property callout_sites

property size

property binary

Get the object this function belongs to. :return: The object this function belongs to.

property offset: int

the function’s binary offset (i.e., non-rebased address)

Type:

return

property symbol: None | Symbol

the function’s Symbol, if any

Type:

return

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.

Return type:

Iterable[int]

Returns:

A view 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.

property graph

Get a local transition graph. A local transition graph is a transition graph that only contains nodes that belong to the current function. All edges, except for the edges going out from the current function or coming from outside the current function, are included.

The generated graph is cached in self._local_transition_graph.

Returns:

A local transition graph.

Return type:

networkx.DiGraph

graph_ex(exception_edges=True)

Get a local transition graph with a custom configuration. A local transition graph is a transition graph that only contains nodes that belong to the current function. This method allows user to exclude certain types of edges together with the nodes that are only reachable through such edges, such as exception edges.

The generated graph is not cached.

Parameters:

exception_edges (bool) – Should exception edges and the nodes that are only reachable through exception edges be kept.

Returns:

A local transition graph with a special configuration.

Return type:

networkx.DiGraph

transition_graph_ex(exception_edges=True)

Get a transition graph with a custom configuration. This method allows user to exclude certain types of edges together with the nodes that are only reachable through such edges, such as exception edges.

The generated graph is not cached.

Parameters:

exception_edges (bool) – Should exception edges and the nodes that are only reachable through exception edges be kept.

Returns:

A local transition graph with a special configuration.

Return type:

networkx.DiGraph

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.

Return networkx.DiGraph:

A subgraph.

instruction_size(insn_addr)

Get the size of the instruction specified by insn_addr.

Parameters:

insn_addr (int) – Address of the instruction

Return int:

Size of the instruction in bytes, or None if the instruction is not found.

addr_to_instruction_addr(addr)

Obtain the address of the instruction that covers @addr.

Parameters:

addr (int) – An address.

Returns:

Address of the instruction that covers @addr, or None if this addr is not covered by any instruction of this function.

Return type:

int or None

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.

classmethod parse(s, **kwargs)

Parse a bytes object and create a class object.

Parameters:

s (bytes) – A bytes object.

Returns:

A class object.

Return type:

cls

serialize()

Serialize the class object and returns a bytes object.

Returns:

A bytes object.

Return type:

bytes

property arguments

property has_return

property 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(ignore_binary_name=False, binary_name_hint=None)

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.

Parameters:

• ignore_binary_name (bool) – Do not rely on the executable or library where the function belongs to determine its source library. This is useful when working on statically linked binaries (because all functions will belong to the main executable). We will search for all libraries in angr to find the first declaration match.

• binary_name_hint (Optional[str]) – Substring of the library name where this function might be originally coming from. Useful for FLIRT-identified functions in statically linked binaries.

Return type:

bool

Returns:

True if a declaration is found and self.prototype and self.calling_convention are updated. False if we fail to find a matching function declaration, in which case self.prototype or self.calling_convention will be kept untouched.

property demangled_name

apply_definition(definition, calling_convention=None)

Return type:

None

Parameters:

• definition (str) –

• calling_convention (SimCC | Type[SimCC] | None) –

functions_called()

Return type:

Set[Function]

Returns:

The set of all functions that can be reached from the function represented by self.

copy()

pp(**kwargs)

Pretty-print the function disassembly.

class angr.knowledge_plugins.functions.function_parser.FunctionParser

Bases: object

The implementation of the serialization methods for the <Function> class.

static serialize(function)

:return :

static parse_from_cmsg(cmsg, function_manager=None, project=None, all_func_addrs=None)

Parameters:

cmsg – The data to instanciate the <Function> from.

Return Function:

class angr.knowledge_plugins.functions.soot_function.SootFunction(function_manager, addr, name=None, syscall=None)

Bases: Function

A representation of a function and various information about it.

__init__(function_manager, addr, name=None, syscall=None)

Function constructor for Soot

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_plt

is_simprocedure

binary_name

bp_on_stack

retaddr_on_stack

sp_delta

calling_convention: Optional[SimCC]

prototype: Optional[SimTypeFunction]

property alignment

property returning

prepared_registers

prepared_stack_variables

registers_read_afterwards

startpoint

info

tags

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

is_default_name

from_signature

is_alignment

is_prototype_guessed: bool

ran_cca

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

addr_to_instruction_addr(addr)

Obtain the address of the instruction that covers @addr.

Parameters:

addr (int) – An address.

Returns:

Address of the instruction that covers @addr, or None if this addr is not covered by any instruction of this function.

Return type:

int or None

apply_definition(definition, calling_convention=None)

Return type:

None

Parameters:

• definition (str) –

• calling_convention (SimCC | Type[SimCC] | None) –

property arguments

property binary

Get the object this function belongs to. :return: The object this function belongs to.

property block_addrs

An iterator of all local block addresses in the current function.

Returns:

block addresses.

property 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

property blocks

An iterator of all local blocks in the current function.

Returns:

angr.lifter.Block instances.

property callable

property callout_sites

property code_constants

All of the constants that are used by this functions’s code.

copy()

dbg_draw(filename)

Draw the graph and save it to a PNG file.

dbg_print()

Returns a representation of the list of basic blocks in this function.

property demangled_name

property endpoints

property endpoints_with_type

find_declaration(ignore_binary_name=False, binary_name_hint=None)

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.

Parameters:

• ignore_binary_name (bool) – Do not rely on the executable or library where the function belongs to determine its source library. This is useful when working on statically linked binaries (because all functions will belong to the main executable). We will search for all libraries in angr to find the first declaration match.

• binary_name_hint (Optional[str]) – Substring of the library name where this function might be originally coming from. Useful for FLIRT-identified functions in statically linked binaries.

Return type:

bool

Returns:

True if a declaration is found and self.prototype and self.calling_convention are updated. False if we fail to find a matching function declaration, in which case self.prototype or self.calling_convention will be kept untouched.

functions_called()

Return type:

Set[Function]

Returns:

The set of all functions that can be reached from the function represented by self.

get_block(addr, size=None, byte_string=None)

Getting a block out of the current function.

Parameters:

• addr (int) – The address of the block.

• size (int) – The size of the block. This is optional. If not provided, angr will load

• byte_string (Optional[bytes]) –

Returns:

get_block_size(addr)

Return type:

Optional[int]

Parameters:

addr (int) –

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.

get_call_sites()

Gets a list of all the basic blocks that end in calls.

Return type:

Iterable[int]

Returns:

A view 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_node(addr)

property graph

Get a local transition graph. A local transition graph is a transition graph that only contains nodes that belong to the current function. All edges, except for the edges going out from the current function or coming from outside the current function, are included.

The generated graph is cached in self._local_transition_graph.

Returns:

A local transition graph.

Return type:

networkx.DiGraph

graph_ex(exception_edges=True)

Get a local transition graph with a custom configuration. A local transition graph is a transition graph that only contains nodes that belong to the current function. This method allows user to exclude certain types of edges together with the nodes that are only reachable through such edges, such as exception edges.

The generated graph is not cached.

Parameters:

exception_edges (bool) – Should exception edges and the nodes that are only reachable through exception edges be kept.

Returns:

A local transition graph with a special configuration.

Return type:

networkx.DiGraph

property has_return

property has_unresolved_calls

property has_unresolved_jumps

instruction_size(insn_addr)

Get the size of the instruction specified by insn_addr.

Parameters:

insn_addr (int) – Address of the instruction

Return int:

Size of the instruction in bytes, or None if the instruction is not found.

property jumpout_sites

property 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

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

property name

property nodes: Generator[CodeNode, None, None]

property num_arguments

property offset: int

the function’s binary offset (i.e., non-rebased address)

Type:

return

property operations

All of the operations that are done by this functions.

classmethod parse(s, **kwargs)

Parse a bytes object and create a class object.

Parameters:

s (bytes) – A bytes object.

Returns:

A class object.

Return type:

cls

classmethod parse_from_cmessage(cmsg, **kwargs)

Parameters:

cmsg –

Return Function:

The function instantiated out of the cmsg data.

pp(**kwargs)

Pretty-print the function disassembly.

property project

property ret_sites

property retout_sites

serialize()

Serialize the class object and returns a bytes object.

Returns:

A bytes object.

Return type:

bytes

serialize_to_cmessage()

Serialize the class object and returns a protobuf cmessage object.

Returns:

A protobuf cmessage object.

Return type:

protobuf.cmessage

property size

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.

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.

Return networkx.DiGraph:

A subgraph.

property symbol: None | Symbol

the function’s Symbol, if any

Type:

return

transition_graph_ex(exception_edges=True)

Get a transition graph with a custom configuration. This method allows user to exclude certain types of edges together with the nodes that are only reachable through such edges, such as exception edges.

The generated graph is not cached.

Parameters:

exception_edges (bool) – Should exception edges and the nodes that are only reachable through exception edges be kept.

Returns:

A local transition graph with a special configuration.

Return type:

networkx.DiGraph

class angr.knowledge_plugins.variables.variable_access.VariableAccessSort

Bases: object

Provides enums for variable access types.

WRITE = 0

READ = 1

REFERENCE = 2

class angr.knowledge_plugins.variables.variable_access.VariableAccess(variable, access_type, location, offset, atom_hash=None)

Bases: Serializable

Describes a variable access.

__init__(variable, access_type, location, offset, atom_hash=None)

variable: SimVariable

access_type: int

location: CodeLocation

offset: Optional[int]

atom_hash: Optional[int]

serialize_to_cmessage()

Serialize the class object and returns a protobuf cmessage object.

Returns:

A protobuf cmessage object.

Return type:

protobuf.cmessage

classmethod parse_from_cmessage(cmsg, variable_by_ident=None, **kwargs)

Parse a protobuf cmessage and create a class object.

Parameters:

• cmsg – The probobuf cmessage object.

• variable_by_ident (Dict[str, SimVariable] | None) –

Returns:

A unserialized class object.

Return type:

cls

classmethod parse(s, **kwargs)

Parse a bytes object and create a class object.

Parameters:

s (bytes) – A bytes object.

Returns:

A class object.

Return type:

cls

serialize()

Serialize the class object and returns a bytes object.

Returns:

A bytes object.

Return type:

bytes

class angr.knowledge_plugins.variables.variable_manager.VariableType

Bases: object

Describes variable types.

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.

__init__(register_region, stack_region)

register_region

stack_region

class angr.knowledge_plugins.variables.variable_manager.VariableManagerInternal(manager, func_addr=None)

Bases: Serializable

Manage variables for a function. It is meant to be used internally by VariableManager, but it’s common to be given a reference to one in response to a query for “the variables for a given function”. Maybe a better name would be “VariableManagerScope”.

__init__(manager, func_addr=None)

set_manager(manager)

Parameters:

manager (VariableManager) –

serialize_to_cmessage()

Serialize the class object and returns a protobuf cmessage object.

Returns:

A protobuf cmessage object.

Return type:

protobuf.cmessage

classmethod parse_from_cmessage(cmsg, variable_manager=None, func_addr=None, **kwargs)

Parse a protobuf cmessage and create a class object.

Parameters:

cmsg – The probobuf cmessage object.

Returns:

A unserialized class object.

Return type:

cls

next_variable_ident(sort)

add_variable(sort, start, variable)

set_variable(sort, start, variable)

Parameters:

variable (SimVariable) –

write_to(variable, offset, location, overwrite=False, atom=None)

read_from(variable, offset, location, overwrite=False, atom=None)

reference_at(variable, offset, location, overwrite=False, atom=None)

make_phi_node(block_addr, *variables)

Create a phi variable for variables at block block_addr.

Parameters:

• block_addr (int) – The address of the current block.

• variables – Variables that the phi variable represents.

Returns:

The created phi variable.

set_live_variables(addr, register_region, stack_region)

find_variables_by_insn(ins_addr, sort)

is_variable_used_at(variable, loc)

Return type:

bool

Parameters:

• variable (SimVariable) –

• loc (Tuple[int, int]) –

find_variable_by_stmt(block_addr, stmt_idx, sort, block_idx=None)

Parameters:

block_idx (int | None) –

find_variables_by_stmt(block_addr, stmt_idx, sort, block_idx=None)

Return type:

List[Tuple[SimVariable, int]]

Parameters:

• block_addr (int) –

• stmt_idx (int) –

• sort (str) –

• block_idx (int | None) –

find_variable_by_atom(block_addr, stmt_idx, atom, block_idx=None)

Parameters:

block_idx (int | None) –

find_variables_by_atom(block_addr, stmt_idx, atom, block_idx=None)

Return type:

Set[Tuple[SimVariable, int]]

Parameters:

block_idx (int | None) –

find_variables_by_stack_offset(offset)

Return type:

Set[SimVariable]

Parameters:

offset (int) –

find_variables_by_register(reg)

Return type:

Set[SimVariable]

Parameters:

reg (str | int) –

get_variable_accesses(variable, same_name=False)

Return type:

List[VariableAccess]

Parameters:

• variable (SimVariable) –

• same_name (bool) –

get_variables(sort=None, collapse_same_ident=False)

Get a list of variables.

Parameters:

• sort (str or None) – 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

get_global_variables(addr)

Get global variable by the address of the variable.

Parameters:

addr (int) – Address of the variable.

Returns:

A set of variables or an empty set if no variable exists.

is_phi_variable(var)

Test if var is a phi variable.

Parameters:

var (SimVariable) – The variable instance.

Returns:

True if var is a phi variable, False otherwise.

Return type:

bool

get_phi_subvariables(var)

Get sub-variables that phi variable var represents.

Parameters:

var (SimVariable) – The variable instance.

Returns:

A set of sub-variables, or an empty set if var is not a phi variable.

Return type:

set

get_phi_variables(block_addr)

Get a dict of phi variables and their corresponding variables.

Parameters:

block_addr (int) – Address of the block.

Returns:

A dict of phi variables of an empty dict if there are no phi variables at the block.

Return type:

dict

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(labels=None, types=None)

Assign default names to all SSA variables.

Parameters:

labels – Known labels in the binary.

Returns:

None

assign_unified_variable_names(labels=None, reset=False)

Assign default names to all unified variables.

Parameters:

• labels – Known labels in the binary.

• reset (bool) – Reset all variable names or not.

Returns:

None

set_variable_type(var, ty, name=None, override_bot=True, all_unified=False, mark_manual=False)

Return type:

None

Parameters:

• var (SimVariable) –

• ty (SimType) –

• name (str | None) –

• override_bot (bool) –

• all_unified (bool) –

• mark_manual (bool) –

get_variable_type(var)

Return type:

Optional[SimType]

remove_types()

unify_variables()

Map SSA variables to a unified variable. Fill in self._unified_variables.

Return type:

None

set_unified_variable(variable, unified)

Set the unified variable for a given SSA variable.

Parameters:

• variable (SimVariable) – The SSA variable.

• unified (SimVariable) – The unified variable.

Return type:

None

Returns:

None

unified_variable(variable)

Return the unified variable for a given SSA variable,

Parameters:

variable (SimVariable) – The SSA variable.

Return type:

Optional[SimVariable]

Returns:

The unified variable, or None if there is no such SSA variable.

classmethod parse(s, **kwargs)

Parse a bytes object and create a class object.

Parameters:

s (bytes) – A bytes object.

Returns:

A class object.

Return type:

cls

serialize()

Serialize the class object and returns a bytes object.

Returns:

A bytes object.

Return type:

bytes

class angr.knowledge_plugins.variables.variable_manager.VariableManager(kb)

Bases: KnowledgeBasePlugin

Manage variables.

__init__(kb)

has_function_manager(key)

Return type:

bool

Parameters:

key (int) –

get_function_manager(func_addr)

Return type:

VariableManagerInternal

initialize_variable_names()

Return type:

None

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.

Return type:

List[VariableAccess]

Returns:

All references to the variable.

copy()

static convert_variable_list(vlist, manager)

Parameters:

• vlist (List[Variable]) –

• manager (VariableManagerInternal) –

load_from_dwarf(cu_list=None)

Parameters:

cu_list (List[CompilationUnit] | None) –

static register_default(name, cls)

class angr.knowledge_plugins.debug_variables.DebugVariableContainer

Bases: object

Variable tree for variables with same name to lock up which variable is visible at a given program counter address.

__init__()

It is recommended to use DebugVariableManager.add_variable() instead

from_pc(pc)

Returns the visible variable (if any) for a given pc address.

Return type:

Variable

class angr.knowledge_plugins.debug_variables.DebugVariable(low_pc, high_pc, cle_variable)

Bases: DebugVariableContainer

Variables:

• low_pc – Start of the visibility scope of the variable as program counter address (rebased)

• high_pc – End of the visibility scope of the variable as program counter address (rebased)

• cle_variable – Original variable from cle

Parameters:

• low_pc (int) –

• high_pc (int) –

• cle_variable (Variable) –

__init__(low_pc, high_pc, cle_variable)

It is recommended to use DebugVariableManager.add_variable() instead

Parameters:

• low_pc (int) –

• high_pc (int) –

• cle_variable (Variable) –

from_pc(pc)

Returns the visible variable (if any) for a given pc address.

Return type:

Variable

contains(dvar)

Return type:

bool

Parameters:

dvar (DebugVariable) –

test_unsupported_overlap(dvar)

Test for an unsupported overlapping

Parameters:

dvar (DebugVariable) – Second DebugVariable to compare with

Return type:

bool

Returns:

True if there is an unsupported overlapping

class angr.knowledge_plugins.debug_variables.DebugVariableManager(kb)

Bases: KnowledgeBasePlugin

Structure to manage and access variables with different visibility scopes.

Parameters:

kb (KnowledgeBase) –

__init__(kb)

Parameters:

kb (KnowledgeBase) –

from_name_and_pc(var_name, pc_addr)

Get a variable from its string in the scope of pc.

Return type:

Variable

Parameters:

• var_name (str) –

• pc_addr (int) –

from_name(var_name)

Get the variable container for all variables named var_name

Parameters:

var_name (str) – name for a variable

Return type:

DebugVariableContainer

add_variable(cle_var, low_pc, high_pc)

Add/load a variable

Parameters:

• cle_variable – The variable to add

• low_pc (int) – Start of the visibility scope of the variable as program counter address (rebased)

• high_pc (int) – End of the visibility scope of the variable as program counter address (rebased)

• cle_var (Variable) –

add_variable_list(vlist, low_pc, high_pc)

Add all variables in a list with the same visibility range

Parameters:

• vlist (List[Variable]) – A list of cle varibles to add

• low_pc (int) – Start of the visibility scope as program counter address (rebased)

• high_pc (int) – End of the visibility scope as program counter address (rebased)

load_from_dwarf(elf_object=None, cu=None)

Automatically load all variables (global/local) from the DWARF debugging info

Parameters:

• elf_object (Optional[ELF]) – Optional, when only one elf object should be considered (e.g. p.loader.main_object)

• cu (Optional[CompilationUnit]) – Optional, when only one compilation unit should be considered

copy()

static register_default(name, cls)

class angr.knowledge_plugins.structured_code.manager.StructuredCodeManager(kb)

Bases: KnowledgeBasePlugin

__init__(kb)

discard(key)

available_flavors(item)

copy()

static register_default(name, cls)

class angr.knowledge_plugins.key_definitions.atoms.AtomKind(value)

Bases: Enum

An enum indicating the class of an atom

REGISTER = 1

MEMORY = 2

TMP = 3

GUARD = 4

CONSTANT = 5

class angr.knowledge_plugins.key_definitions.atoms.Atom(size)

Bases: object

This class represents a data storage location manipulated by IR instructions.

It could either be a Tmp (temporary variable), a Register, a MemoryLocation.

__init__(size)

Parameters:

size – The size of the atom in bytes

size

property bits: int

static from_ail_expr(expr, arch, full_reg=False)

Return type:

Register

Parameters:

• expr (Expression) –

• arch (Arch) –

• full_reg (bool) –

static from_argument(argument, arch, full_reg=False, sp=None)

Instanciate an Atom from a given argument.

Parameters:

• argument (SimFunctionArgument) – The argument to create a new atom from.

• registers – A mapping representing the registers of a given architecture.

• full_reg – Whether to return an atom indicating the entire register if the argument only specifies a slice of the register.

• sp (Optional[int]) – The current stack offset. Optional. Only used when argument is a SimStackArg.

• arch (Arch) –

Return type:

Union[Register, MemoryLocation]

static reg(thing, size=None, arch=None)

Create a Register atom.

Parameters:

• thing (Union[str, NewType()(RegisterOffset, int)]) – The register offset (e.g., project.arch.registers[“rax”][0]) or the register name (e.g., “rax”).

• size (Optional[int]) – Size of the register atom. Must be provided when creating the atom using a register offset.

• arch (Optional[Arch]) – The architecture. Must be provided when creating the atom using a register name.

Return type:

Register

Returns:

The Register Atom object.

static register(thing, size=None, arch=None)

Create a Register atom.

Parameters:

• thing (Union[str, NewType()(RegisterOffset, int)]) – The register offset (e.g., project.arch.registers[“rax”][0]) or the register name (e.g., “rax”).

• size (Optional[int]) – Size of the register atom. Must be provided when creating the atom using a register offset.

• arch (Optional[Arch]) – The architecture. Must be provided when creating the atom using a register name.

Return type:

Register

Returns:

The Register Atom object.

static mem(addr, size, endness=None)

Create a MemoryLocation atom,

Parameters:

• addr (Union[SpOffset, HeapAddress, int]) – The memory location. Can be an SpOffset for stack variables, an int for global memory variables, or a HeapAddress for items on the heap.

• size (int) – Size of the atom.

• endness (Optional[str]) – Optional, either “Iend_LE” or “Iend_BE”.

Return type:

MemoryLocation

Returns:

The MemoryLocation Atom object.

static memory(addr, size, endness=None)

Create a MemoryLocation atom,

Parameters:

• addr (Union[SpOffset, HeapAddress, int]) – The memory location. Can be an SpOffset for stack variables, an int for global memory variables, or a HeapAddress for items on the heap.

• size (int) – Size of the atom.

• endness (Optional[str]) – Optional, either “Iend_LE” or “Iend_BE”.

Return type:

MemoryLocation

Returns:

The MemoryLocation Atom object.

class angr.knowledge_plugins.key_definitions.atoms.GuardUse(target)

Bases: Atom

Implements a guard use.

__init__(target)

Parameters:

size – The size of the atom in bytes

target

property bits: int

static from_ail_expr(expr, arch, full_reg=False)

Return type:

Register

Parameters:

• expr (Expression) –

• arch (Arch) –

• full_reg (bool) –

static from_argument(argument, arch, full_reg=False, sp=None)

Instanciate an Atom from a given argument.

Parameters:

• argument (SimFunctionArgument) – The argument to create a new atom from.

• registers – A mapping representing the registers of a given architecture.

• full_reg – Whether to return an atom indicating the entire register if the argument only specifies a slice of the register.

• sp (Optional[int]) – The current stack offset. Optional. Only used when argument is a SimStackArg.

• arch (Arch) –

Return type:

Union[Register, MemoryLocation]

static mem(addr, size, endness=None)

Create a MemoryLocation atom,

Parameters:

• addr (Union[SpOffset, HeapAddress, int]) – The memory location. Can be an SpOffset for stack variables, an int for global memory variables, or a HeapAddress for items on the heap.

• size (int) – Size of the atom.

• endness (Optional[str]) – Optional, either “Iend_LE” or “Iend_BE”.

Return type:

MemoryLocation

Returns:

The MemoryLocation Atom object.

static memory(addr, size, endness=None)

Create a MemoryLocation atom,

Parameters:

• addr (Union[SpOffset, HeapAddress, int]) – The memory location. Can be an SpOffset for stack variables, an int for global memory variables, or a HeapAddress for items on the heap.

• size (int) – Size of the atom.

• endness (Optional[str]) – Optional, either “Iend_LE” or “Iend_BE”.

Return type:

MemoryLocation

Returns:

The MemoryLocation Atom object.

static reg(thing, size=None, arch=None)

Create a Register atom.

Parameters:

• thing (Union[str, NewType()(RegisterOffset, int)]) – The register offset (e.g., project.arch.registers[“rax”][0]) or the register name (e.g., “rax”).

• size (Optional[int]) – Size of the register atom. Must be provided when creating the atom using a register offset.

• arch (Optional[Arch]) – The architecture. Must be provided when creating the atom using a register name.

Return type:

Register

Returns:

The Register Atom object.

static register(thing, size=None, arch=None)

Create a Register atom.

Parameters:

• thing (Union[str, NewType()(RegisterOffset, int)]) – The register offset (e.g., project.arch.registers[“rax”][0]) or the register name (e.g., “rax”).

• size (Optional[int]) – Size of the register atom. Must be provided when creating the atom using a register offset.

• arch (Optional[Arch]) – The architecture. Must be provided when creating the atom using a register name.

Return type:

Register

Returns:

The Register Atom object.

size

class angr.knowledge_plugins.key_definitions.atoms.ConstantSrc(value, size)

Bases: Atom

Represents a constant.

Parameters:

• value (int) –

• size (int) –

__init__(value, size)

Parameters:

• size (int) – The size of the atom in bytes

• value (int) –

value: int

property bits: int

static from_ail_expr(expr, arch, full_reg=False)

Return type:

Register

Parameters:

• expr (Expression) –

• arch (Arch) –

• full_reg (bool) –

static from_argument(argument, arch, full_reg=False, sp=None)

Instanciate an Atom from a given argument.

Parameters:

• argument (SimFunctionArgument) – The argument to create a new atom from.

• registers – A mapping representing the registers of a given architecture.

• full_reg – Whether to return an atom indicating the entire register if the argument only specifies a slice of the register.

• sp (Optional[int]) – The current stack offset. Optional. Only used when argument is a SimStackArg.

• arch (Arch) –

Return type:

Union[Register, MemoryLocation]

static mem(addr, size, endness=None)

Create a MemoryLocation atom,

Parameters:

• addr (Union[SpOffset, HeapAddress, int]) – The memory location. Can be an SpOffset for stack variables, an int for global memory variables, or a HeapAddress for items on the heap.

• size (int) – Size of the atom.

• endness (Optional[str]) – Optional, either “Iend_LE” or “Iend_BE”.

Return type:

MemoryLocation

Returns:

The MemoryLocation Atom object.

static memory(addr, size, endness=None)

Create a MemoryLocation atom,

Parameters:

• addr (Union[SpOffset, HeapAddress, int]) – The memory location. Can be an SpOffset for stack variables, an int for global memory variables, or a HeapAddress for items on the heap.

• size (int) – Size of the atom.

• endness (Optional[str]) – Optional, either “Iend_LE” or “Iend_BE”.

Return type:

MemoryLocation

Returns:

The MemoryLocation Atom object.

static reg(thing, size=None, arch=None)

Create a Register atom.

Parameters:

• thing (Union[str, NewType()(RegisterOffset, int)]) – The register offset (e.g., project.arch.registers[“rax”][0]) or the register name (e.g., “rax”).

• size (Optional[int]) – Size of the register atom. Must be provided when creating the atom using a register offset.

• arch (Optional[Arch]) – The architecture. Must be provided when creating the atom using a register name.

Return type:

Register

Returns:

The Register Atom object.

static register(thing, size=None, arch=None)

Create a Register atom.

Parameters:

• thing (Union[str, NewType()(RegisterOffset, int)]) – The register offset (e.g., project.arch.registers[“rax”][0]) or the register name (e.g., “rax”).

• size (Optional[int]) – Size of the register atom. Must be provided when creating the atom using a register offset.

• arch (Optional[Arch]) – The architecture. Must be provided when creating the atom using a register name.

Return type:

Register

Returns:

The Register Atom object.

size

class angr.knowledge_plugins.key_definitions.atoms.Tmp(tmp_idx, size)

Bases: Atom

Represents a variable used by the IR to store intermediate values.

Parameters:

• tmp_idx (int) –

• size (int) –

__init__(tmp_idx, size)

Parameters:

• size (int) – The size of the atom in bytes

• tmp_idx (int) –

tmp_idx

property bits: int

static from_ail_expr(expr, arch, full_reg=False)

Return type:

Register

Parameters:

• expr (Expression) –

• arch (Arch) –

• full_reg (bool) –

static from_argument(argument, arch, full_reg=False, sp=None)

Instanciate an Atom from a given argument.

Parameters:

• argument (SimFunctionArgument) – The argument to create a new atom from.

• registers – A mapping representing the registers of a given architecture.

• full_reg – Whether to return an atom indicating the entire register if the argument only specifies a slice of the register.

• sp (Optional[int]) – The current stack offset. Optional. Only used when argument is a SimStackArg.

• arch (Arch) –

Return type:

Union[Register, MemoryLocation]

static mem(addr, size, endness=None)

Create a MemoryLocation atom,

Parameters:

• addr (Union[SpOffset, HeapAddress, int]) – The memory location. Can be an SpOffset for stack variables, an int for global memory variables, or a HeapAddress for items on the heap.

• size (int) – Size of the atom.

• endness (Optional[str]) – Optional, either “Iend_LE” or “Iend_BE”.

Return type:

MemoryLocation

Returns:

The MemoryLocation Atom object.

static memory(addr, size, endness=None)

Create a MemoryLocation atom,

Parameters:

• addr (Union[SpOffset, HeapAddress, int]) – The memory location. Can be an SpOffset for stack variables, an int for global memory variables, or a HeapAddress for items on the heap.

• size (int) – Size of the atom.

• endness (Optional[str]) – Optional, either “Iend_LE” or “Iend_BE”.

Return type:

MemoryLocation

Returns:

The MemoryLocation Atom object.

static reg(thing, size=None, arch=None)

Create a Register atom.

Parameters:

• thing (Union[str, NewType()(RegisterOffset, int)]) – The register offset (e.g., project.arch.registers[“rax”][0]) or the register name (e.g., “rax”).

• size (Optional[int]) – Size of the register atom. Must be provided when creating the atom using a register offset.

• arch (Optional[Arch]) – The architecture. Must be provided when creating the atom using a register name.

Return type:

Register

Returns:

The Register Atom object.

static register(thing, size=None, arch=None)

Create a Register atom.

Parameters:

• thing (Union[str, NewType()(RegisterOffset, int)]) – The register offset (e.g., project.arch.registers[“rax”][0]) or the register name (e.g., “rax”).

• size (Optional[int]) – Size of the register atom. Must be provided when creating the atom using a register offset.

• arch (Optional[Arch]) – The architecture. Must be provided when creating the atom using a register name.

Return type:

Register

Returns:

The Register Atom object.

size

class angr.knowledge_plugins.key_definitions.atoms.Register(reg_offset, size, arch=None)

Bases: Atom

Represents a given CPU register.

As an IR abstracts the CPU design to target different architectures, registers are represented as a separated memory space. Thus a register is defined by its offset from the base of this memory and its size.

Variables:

• reg_offset (int) – The offset from the base to define its place in the memory bloc.

• size (int) – The size, in number of bytes.

Parameters:

• reg_offset (RegisterOffset) –

• size (int) –

• arch (Arch | None) –

__init__(reg_offset, size, arch=None)

Parameters:

• size (int) – The size of the atom in bytes

• reg_offset (RegisterOffset) –

• arch (Arch | None) –

reg_offset

arch

property name: str

property bits: int

static from_ail_expr(expr, arch, full_reg=False)

Return type:

Register

Parameters:

• expr (Expression) –

• arch (Arch) –

• full_reg (bool) –

static from_argument(argument, arch, full_reg=False, sp=None)

Instanciate an Atom from a given argument.

Parameters:

• argument (SimFunctionArgument) – The argument to create a new atom from.

• registers – A mapping representing the registers of a given architecture.

• full_reg – Whether to return an atom indicating the entire register if the argument only specifies a slice of the register.

• sp (Optional[int]) – The current stack offset. Optional. Only used when argument is a SimStackArg.

• arch (Arch) –

Return type:

Union[Register, MemoryLocation]

static mem(addr, size, endness=None)

Create a MemoryLocation atom,

Parameters:

• addr (Union[SpOffset, HeapAddress, int]) – The memory location. Can be an SpOffset for stack variables, an int for global memory variables, or a HeapAddress for items on the heap.

• size (int) – Size of the atom.

• endness (Optional[str]) – Optional, either “Iend_LE” or “Iend_BE”.

Return type:

MemoryLocation

Returns:

The MemoryLocation Atom object.

static memory(addr, size, endness=None)

Create a MemoryLocation atom,

Parameters:

• addr (Union[SpOffset, HeapAddress, int]) – The memory location. Can be an SpOffset for stack variables, an int for global memory variables, or a HeapAddress for items on the heap.

• size (int) – Size of the atom.

• endness (Optional[str]) – Optional, either “Iend_LE” or “Iend_BE”.

Return type:

MemoryLocation

Returns:

The MemoryLocation Atom object.

static reg(thing, size=None, arch=None)

Create a Register atom.

Parameters:

• thing (Union[str, NewType()(RegisterOffset, int)]) – The register offset (e.g., project.arch.registers[“rax”][0]) or the register name (e.g., “rax”).

• size (Optional[int]) – Size of the register atom. Must be provided when creating the atom using a register offset.

• arch (Optional[Arch]) – The architecture. Must be provided when creating the atom using a register name.

Return type:

Register

Returns:

The Register Atom object.

static register(thing, size=None, arch=None)

Create a Register atom.

Parameters:

• thing (Union[str, NewType()(RegisterOffset, int)]) – The register offset (e.g., project.arch.registers[“rax”][0]) or the register name (e.g., “rax”).

• size (Optional[int]) – Size of the register atom. Must be provided when creating the atom using a register offset.

• arch (Optional[Arch]) – The architecture. Must be provided when creating the atom using a register name.

Return type:

Register

Returns:

The Register Atom object.

size

class angr.knowledge_plugins.key_definitions.atoms.MemoryLocation(addr, size, endness=None)

Bases: Atom

Represents a memory slice.

It is characterized by its address and its size.

Parameters:

• addr (SpOffset | HeapAddress | int) –

• size (int) –

• endness (str | None) –

__init__(addr, size, endness=None)

Parameters:

• addr (int) – The address of the beginning memory location slice.

• size (int) – The size of the represented memory location, in bytes.

• endness (str | None) –

addr: Union[SpOffset, int, BV]

endness

property is_on_stack: bool

True if this memory location is located on the stack.

property symbolic: bool

property bits: int

static from_ail_expr(expr, arch, full_reg=False)

Return type:

Register

Parameters:

• expr (Expression) –

• arch (Arch) –

• full_reg (bool) –

static from_argument(argument, arch, full_reg=False, sp=None)

Instanciate an Atom from a given argument.

Parameters:

• argument (SimFunctionArgument) – The argument to create a new atom from.

• registers – A mapping representing the registers of a given architecture.

• full_reg – Whether to return an atom indicating the entire register if the argument only specifies a slice of the register.

• sp (Optional[int]) – The current stack offset. Optional. Only used when argument is a SimStackArg.

• arch (Arch) –

Return type:

Union[Register, MemoryLocation]

static mem(addr, size, endness=None)

Create a MemoryLocation atom,

Parameters:

• addr (Union[SpOffset, HeapAddress, int]) – The memory location. Can be an SpOffset for stack variables, an int for global memory variables, or a HeapAddress for items on the heap.

• size (int) – Size of the atom.

• endness (Optional[str]) – Optional, either “Iend_LE” or “Iend_BE”.

Return type:

MemoryLocation

Returns:

The MemoryLocation Atom object.

static memory(addr, size, endness=None)

Create a MemoryLocation atom,

Parameters:

• addr (Union[SpOffset, HeapAddress, int]) – The memory location. Can be an SpOffset for stack variables, an int for global memory variables, or a HeapAddress for items on the heap.

• size (int) – Size of the atom.

• endness (Optional[str]) – Optional, either “Iend_LE” or “Iend_BE”.

Return type:

MemoryLocation

Returns:

The MemoryLocation Atom object.

static reg(thing, size=None, arch=None)

Create a Register atom.

Parameters:

• thing (Union[str, NewType()(RegisterOffset, int)]) – The register offset (e.g., project.arch.registers[“rax”][0]) or the register name (e.g., “rax”).

• size (Optional[int]) – Size of the register atom. Must be provided when creating the atom using a register offset.

• arch (Optional[Arch]) – The architecture. Must be provided when creating the atom using a register name.

Return type:

Register

Returns:

The Register Atom object.

static register(thing, size=None, arch=None)

Create a Register atom.

Parameters:

• thing (Union[str, NewType()(RegisterOffset, int)]) – The register offset (e.g., project.arch.registers[“rax”][0]) or the register name (e.g., “rax”).

• size (Optional[int]) – Size of the register atom. Must be provided when creating the atom using a register offset.

• arch (Optional[Arch]) – The architecture. Must be provided when creating the atom using a register name.

Return type:

Register

Returns:

The Register Atom object.

size

class angr.knowledge_plugins.key_definitions.constants.ObservationPointType(value)

Bases: IntEnum

Enum to replace the previously generic constants This makes it possible to annotate where they are expected by typing something as ObservationPointType instead of Literal[0,1]

OP_BEFORE = 0

OP_AFTER = 1

class angr.knowledge_plugins.key_definitions.definition.DefinitionMatchPredicate(kind=None, bbl_addr=None, ins_addr=None, variable=None, variable_manager=None, stack_offset=None, reg_name=None, heap_offset=None, global_addr=None, tmp_idx=None, const_val=None)

Bases: object

A dataclass indicating several facts which much all must match in order for a definition to match. Largely an internal class; don’t worry about this.

Parameters:

• kind (AtomKind | None) –

• bbl_addr (int | None) –

• ins_addr (int | None) –

• variable (SimVariable | None) –

• variable_manager (VariableManagerInternal | None | Literal[False]) –

• stack_offset (int | None) –

• reg_name (str | int | None) –

• heap_offset (int | None) –

• global_addr (int | None) –

• tmp_idx (int | None) –

• const_val (int | None) –

kind: Optional[AtomKind] = None

bbl_addr: Optional[int] = None

ins_addr: Optional[int] = None

variable: Optional[SimVariable] = None

variable_manager: Union[VariableManagerInternal, None, Literal[False]] = None

stack_offset: Optional[int] = None

reg_name: Union[str, int, None] = None

heap_offset: Optional[int] = None

global_addr: Optional[int] = None

tmp_idx: Optional[int] = None

const_val: Optional[int] = None

static construct(predicate=None, **kwargs)

Return type:

DefinitionMatchPredicate

Parameters:

predicate (DefinitionMatchPredicate | None) –

normalize()

matches(defn)

Return type:

bool

Parameters:

defn (Definition) –

__init__(kind=None, bbl_addr=None, ins_addr=None, variable=None, variable_manager=None, stack_offset=None, reg_name=None, heap_offset=None, global_addr=None, tmp_idx=None, const_val=None)

Parameters:

• kind (AtomKind | None) –

• bbl_addr (int | None) –

• ins_addr (int | None) –

• variable (SimVariable | None) –

• variable_manager (VariableManagerInternal | None | Literal[False]) –

• stack_offset (int | None) –

• reg_name (str | int | None) –

• heap_offset (int | None) –

• global_addr (int | None) –

• tmp_idx (int | None) –

• const_val (int | None) –

Return type:

None

class angr.knowledge_plugins.key_definitions.definition.Definition(atom, codeloc, dummy=False, tags=None)

Bases: Generic[A]

An atom definition.

Variables:

• atom – The atom being defined.

• codeloc – Where this definition is created in the original binary code.

• dummy – Tell whether the definition should be considered dummy or not. During simplification by AILment, definitions marked as dummy will not be removed.

• tags – A set of tags containing information about the definition gathered during analyses.

__init__(atom, codeloc, dummy=False, tags=None)

Parameters:

• atom (A) –

• codeloc (CodeLocation) –

• dummy (bool) –

• tags (Set[Tag] | None) –

atom: TypeVar(A, bound= Atom)

codeloc: CodeLocation

dummy: bool

tags

property offset: int

property size: int

matches(**kwargs)

Return whether this definition has certain characteristics.

Return type:

bool

class angr.knowledge_plugins.key_definitions.environment.Environment(environment=None)

Bases: object

Represent the environment in which a program runs. It’s a mapping of variable names, to claripy.ast.Base that should contain possible addresses, or <UNDEFINED>, at which their respective values are stored.

Note: The <Environment> object does not store the values associated with variables themselves.

Parameters:

environment (Dict[str | Undefined, Set[Base]]) –

__init__(environment=None)

Parameters:

environment (Dict[str | Undefined, Set[Base]] | None) –

get(names)

Parameters:

names (Set[str]) – Potential values for the name of the environment variable to get the pointers of.

Return type:

Tuple[Set[Base], bool]

Returns:

The potential addresses of the values the environment variable can take; And a boolean value telling whether all the names were known of the internal representation (i.e. will be False if one of the queried variable was not found).

set(name, pointers)

Parameters:

• name (Union[str, Undefined]) – Name of the environment variable to which we will associate the pointers.

• pointers (Set[Base]) – New addresses where the new values of the environment variable are located.

merge(*others)

Return type:

Tuple[Environment, bool]

Parameters:

others (Environment) –

class angr.knowledge_plugins.key_definitions.heap_address.HeapAddress(value)

Bases: object

The representation of an address on the heap.

Parameters:

value (int | Undefined) –

__init__(value)

Parameters:

value (int | Undefined) –

property value

class angr.knowledge_plugins.key_definitions.key_definition_manager.RDAObserverControl(func_addr, call_site_block_addrs, call_site_ins_addrs)

Bases: object

Parameters:

• func_addr (int) –

• call_site_block_addrs (Iterable[int]) –

• call_site_ins_addrs (Iterable[int]) –

__init__(func_addr, call_site_block_addrs, call_site_ins_addrs)

Parameters:

• func_addr (int) –

• call_site_block_addrs (Iterable[int]) –

• call_site_ins_addrs (Iterable[int]) –

rda_observe_callback(ob_type, **kwargs)

class angr.knowledge_plugins.key_definitions.key_definition_manager.KeyDefinitionManager(kb)

Bases: KnowledgeBasePlugin

KeyDefinitionManager manages and caches reaching definition models for each function.

For each function, by default we cache the entire reaching definitions model with observed results at the following locations: - Before each call instruction: (‘insn’, address of the call instruction, OP_BEFORE) - After returning from each call: (‘node’, address of the block that ends with a call, OP_AFTER)

Parameters:

kb (KnowledgeBase) –

__init__(kb)

Parameters:

kb (KnowledgeBase) –

has_model(func_addr)

Parameters:

func_addr (int) –

get_model(func_addr)

Parameters:

func_addr (int) –

copy()

Return type:

KeyDefinitionManager

static register_default(name, cls)

class angr.knowledge_plugins.key_definitions.live_definitions.DefinitionAnnotation(definition)

Bases: Annotation

__init__(definition)

definition

property relocatable

Returns whether this annotation can be relocated in a simplification.

Returns:

True if it can be relocated, false otherwise.

property eliminatable

Returns whether this annotation can be eliminated in a simplification.

Returns:

True if eliminatable, False otherwise

relocate(src, dst)

This is called when an annotation has to be relocated because of simplifications.

Consider the following case:

x = claripy.BVS(‘x’, 32) zero = claripy.BVV(0, 32).add_annotation(your_annotation) y = x + zero

Here, one of three things can happen:

1. if your_annotation.eliminatable is True, the simplifiers will simply eliminate your_annotation along with zero and y is x will hold

2. elif your_annotation.relocatable is False, the simplifier will abort and y will never be simplified

3. elif your_annotation.relocatable is True, the simplifier will run, determine that the simplified result of x + zero will be x. It will then call your_annotation.relocate(zero, x) to move the annotation away from the AST that is about to be eliminated.

Parameters:

• src – the old AST that was eliminated in the simplification

• dst – the new AST (the result of a simplification)

Returns:

the annotation that will be applied to dst

class angr.knowledge_plugins.key_definitions.live_definitions.LiveDefinitions(arch, track_tmps=False, canonical_size=8, register_definitions=None, stack_definitions=None, memory_definitions=None, heap_definitions=None, tmps=None, register_uses=None, stack_uses=None, heap_uses=None, memory_uses=None, tmp_uses=None)

Bases: object

A LiveDefinitions instance contains definitions and uses for register, stack, memory, and temporary variables, uncovered during the analysis.

Parameters:

• arch (Arch) –

• track_tmps (bool) –

INITIAL_SP_32BIT = 2147418112

INITIAL_SP_64BIT = 140737488289792

__init__(arch, track_tmps=False, canonical_size=8, register_definitions=None, stack_definitions=None, memory_definitions=None, heap_definitions=None, tmps=None, register_uses=None, stack_uses=None, heap_uses=None, memory_uses=None, tmp_uses=None)

Parameters:

• arch (Arch) –

• track_tmps (bool) –

project

arch

track_tmps

register_definitions

stack_definitions

memory_definitions

heap_definitions

tmps: Dict[int, Set[Definition]]

register_uses

stack_uses

heap_uses

memory_uses

tmp_uses: Dict[int, Set[CodeLocation]]

uses_by_codeloc: Dict[CodeLocation, Set[Definition]]

property registers: MultiValuedMemory

property stack: MultiValuedMemory

property memory: MultiValuedMemory

property heap: MultiValuedMemory

copy()

Return type:

LiveDefinitions

static top(bits)

Get a TOP value.

Parameters:

bits (int) – Width of the TOP value (in bits).

Returns:

The TOP value.

static is_top(expr)

Check if the given expression is a TOP value.

Parameters:

expr – The given expression.

Return type:

bool

Returns:

True if the expression is TOP, False otherwise.

stack_address(offset)

Return type:

Base

Parameters:

offset (int) –

static is_stack_address(addr)

Return type:

bool

Parameters:

addr (Base) –

static get_stack_offset(addr, had_stack_base=False)

Return type:

Optional[int]

Parameters:

addr (Base) –

static annotate_with_def(symvar, definition)

Parameters:

• symvar (Base) –

• definition (Definition) –

Returns:

static extract_defs(symvar)

Return type:

Generator[Definition, None, None]

Parameters:

symvar (Base) –

static extract_defs_from_mv(mv)

Return type:

Generator[Definition, None, None]

Parameters:

mv (MultiValues) –

get_sp()

Return the concrete value contained by the stack pointer.

Return type:

int

get_sp_offset()

Return the offset of the stack pointer.

Return type:

int

get_stack_address(offset)

Return type:

Optional[int]

Parameters:

offset (Base) –

stack_offset_to_stack_addr(offset)

Return type:

int

merge(*others)

Return type:

Tuple[LiveDefinitions, bool]

kill_definitions(atom)

Overwrite existing definitions w.r.t ‘atom’ with a dummy definition instance. A dummy definition will not be removed during simplification.

Parameters:

atom (Atom) –

Return type:

None

Returns:

None

kill_and_add_definition(atom, code_loc, data, dummy=False, tags=None, endness=None, annotated=False)

Return type:

Optional[MultiValues]

Parameters:

• atom (Atom) –

• code_loc (CodeLocation) –

• data (MultiValues) –

• tags (Set[Tag] | None) –

add_use(atom, code_loc, expr=None)

Return type:

None

Parameters:

• atom (Atom) –

• code_loc (CodeLocation) –

• expr (Any | None) –

add_use_by_def(definition, code_loc, expr=None)

Return type:

None

Parameters:

• definition (Definition) –

• code_loc (CodeLocation) –

• expr (Any | None) –

get_definitions(atom)

Return type:

Iterable[Definition]

Parameters:

atom (Atom) –

get_tmp_definitions(tmp_idx)

Return type:

Iterable[Definition]

Parameters:

tmp_idx (int) –

get_register_definitions(reg_offset, size, endness=None)

Return type:

Iterable[Definition]

Parameters:

• reg_offset (int) –

• size (int) –

get_stack_values(stack_offset, size, endness)

Return type:

Optional[MultiValues]

Parameters:

• stack_offset (int) –

• size (int) –

• endness (Endness) –

get_stack_definitions(stack_offset, size, endness)

Return type:

Iterable[Definition]

Parameters:

• stack_offset (int) –

• size (int) –

get_heap_definitions(heap_addr, size, endness)

Return type:

Iterable[Definition]

Parameters:

• heap_addr (int) –

• size (int) –

get_memory_definitions(addr, size, endness)

Return type:

Iterable[Definition]

Parameters:

• addr (int) –

• size (int) –

get_definitions_from_atoms(atoms)

Return type:

Iterable[Definition]

Parameters:

atoms (Iterable[Atom]) –

get_value_from_definition(definition)

Return type:

Optional[MultiValues]

Parameters:

definition (Definition) –

get_one_value_from_definition(definition)

Return type:

Optional[Base]

Parameters:

definition (Definition) –

get_concrete_value_from_definition(definition)

Return type:

Optional[int]

Parameters:

definition (Definition) –

get_value_from_atom(atom)

Return type:

Optional[MultiValues]

Parameters:

atom (Atom) –

get_one_value_from_atom(atom)

Return type:

Optional[Base]

Parameters:

atom (Atom) –

get_concrete_value_from_atom(atom)

Return type:

Optional[int]

Parameters:

atom (Atom) –

get_values(spec)

Return type:

Optional[MultiValues]

Parameters:

spec (Atom | Definition) –

get_one_value(spec)

Return type:

Optional[Base]

Parameters:

spec (Atom | Definition) –

get_concrete_value(spec)

Return type:

Optional[int]

Parameters:

spec (Atom | Definition) –

add_register_use(reg_offset, size, code_loc, expr=None)

Return type:

None

Parameters:

• reg_offset (int) –

• size (int) –

• code_loc (CodeLocation) –

• expr (Any | None) –

add_register_use_by_def(def_, code_loc, expr=None)

Return type:

None

Parameters:

• def_ (Definition) –

• code_loc (CodeLocation) –

• expr (Any | None) –

add_stack_use(atom, code_loc, expr=None)

Return type:

None

Parameters:

• atom (MemoryLocation) –

• code_loc (CodeLocation) –

• expr (Any | None) –

add_stack_use_by_def(def_, code_loc, expr=None)

Return type:

None

Parameters:

• def_ (Definition) –

• code_loc (CodeLocation) –

• expr (Any | None) –

add_heap_use(atom, code_loc, expr=None)

Return type:

None

Parameters:

• atom (MemoryLocation) –

• code_loc (CodeLocation) –

• expr (Any | None) –

add_heap_use_by_def(def_, code_loc, expr=None)

Return type:

None

Parameters:

• def_ (Definition) –

• code_loc (CodeLocation) –

• expr (Any | None) –

add_memory_use(atom, code_loc, expr=None)

Return type:

None

Parameters:

• atom (MemoryLocation) –

• code_loc (CodeLocation) –

• expr (Any | None) –

add_memory_use_by_def(def_, code_loc, expr=None)

Return type:

None

Parameters:

• def_ (Definition) –

• code_loc (CodeLocation) –

• expr (Any | None) –

add_tmp_use(atom, code_loc)

Return type:

None

Parameters:

• atom (Tmp) –

• code_loc (CodeLocation) –

add_tmp_use_by_def(def_, code_loc)

Return type:

None

Parameters:

• def_ (Definition) –

• code_loc (CodeLocation) –

class angr.knowledge_plugins.key_definitions.rd_model.ReachingDefinitionsModel(func_addr=None)

Bases: object

Models the definitions, uses, and memory of a ReachingDefinitionState object

Parameters:

func_addr (int | None) –

__init__(func_addr=None)

Parameters:

func_addr (int | None) –

copy()

Return type:

ReachingDefinitionsModel

merge(model)

Parameters:

model (ReachingDefinitionsModel) –

get_observation_by_insn(ins_addr, kind)

Return type:

Optional[LiveDefinitions]

Parameters:

• ins_addr (int | CodeLocation) –

• kind (ObservationPointType) –

get_observation_by_node(node_addr, kind)

Return type:

Optional[LiveDefinitions]

Parameters:

• node_addr (int | CodeLocation) –

• kind (ObservationPointType) –

get_observation_by_stmt(arg1, arg2, arg3=None, *, block_idx=None)

Classes to structure the different types of <Tag>s that can be attached to <Definition>s.

• Tag

  • FunctionTag

    • ParameterTag

    • LocalVariableTag

    • ReturnValueTag

  • InitialValueTag

class angr.knowledge_plugins.key_definitions.tag.Tag(metadata=None)

Bases: object

A tag for a Definition that can carry different kinds of metadata.

Parameters:

metadata (object) –

__init__(metadata=None)

Parameters:

metadata (object | None) –

class angr.knowledge_plugins.key_definitions.tag.FunctionTag(function=None, metadata=None)

Bases: Tag

A tag for a definition created (or used) in the context of a function.

Parameters:

• function (int) –

• metadata (object) –

__init__(function=None, metadata=None)

Parameters:

• function (int | None) –

• metadata (object | None) –

class angr.knowledge_plugins.key_definitions.tag.SideEffectTag(function=None, metadata=None)

Bases: FunctionTag

A tag for a definition created or used as a side-effect of a function.

Example: The <MemoryLocation> pointed by rdi during a sprintf.

Parameters:

• function (int) –

• metadata (object) –

__init__(function=None, metadata=None)

Parameters:

• function (int | None) –

• metadata (object | None) –

class angr.knowledge_plugins.key_definitions.tag.ParameterTag(function=None, metadata=None)

Bases: FunctionTag

A tag for a definition of a parameter.

Parameters:

• function (int) –

• metadata (object) –

__init__(function=None, metadata=None)

Parameters:

• function (int | None) –

• metadata (object | None) –

class angr.knowledge_plugins.key_definitions.tag.LocalVariableTag(function=None, metadata=None)

Bases: FunctionTag

A tag for a definition of a local variable of a function.

Parameters:

• function (int) –

• metadata (object) –

__init__(function=None, metadata=None)

Parameters:

• function (int | None) –

• metadata (object | None) –

class angr.knowledge_plugins.key_definitions.tag.ReturnValueTag(function=None, metadata=None)

Bases: FunctionTag

A tag for a definiton of a return value of a function.

Parameters:

• function (int) –

• metadata (object) –

__init__(function=None, metadata=None)

Parameters:

• function (int | None) –

• metadata (object | None) –

class angr.knowledge_plugins.key_definitions.tag.InitialValueTag(metadata=None)

Bases: Tag

A tag for a definiton of an initial value

Parameters:

metadata (object) –

__init__(metadata=None)

Parameters:

metadata (object | None) –

class angr.knowledge_plugins.key_definitions.tag.UnknownSizeTag(metadata=None)

Bases: Tag

A tag for a definiton of an initial value

Parameters:

metadata (object) –

__init__(metadata=None)

Parameters:

metadata (object | None) –

class angr.knowledge_plugins.key_definitions.undefined.Undefined

Bases: object

A TOP-like value indicating an unknown data source. Should live next to raw integers in DataSets.

class angr.knowledge_plugins.key_definitions.unknown_size.UnknownSize

Bases: object

A value indicating an unknown size for elements of DataSets. Should “behave” like an integer.

class angr.knowledge_plugins.key_definitions.uses.Uses(uses_by_definition=None, uses_by_location=None)

Bases: object

Describes uses (including the use location and the use expression) for definitions.

Parameters:

• uses_by_definition (DefaultChainMapCOW | None) –

• uses_by_location (DefaultChainMapCOW | None) –

__init__(uses_by_definition=None, uses_by_location=None)

Parameters:

• uses_by_definition (DefaultChainMapCOW | None) –

• uses_by_location (DefaultChainMapCOW | None) –

add_use(definition, codeloc, expr=None)

Add a use for a given definition.

Parameters:

• definition (Definition) – The definition that is used.

• codeloc (CodeLocation) – The code location where the use occurs.

• expr (Optional[Any]) – The expression that uses the specified definition at this location.

get_uses(definition)

Retrieve the uses of a given definition.

Parameters:

definition (Definition) – The definition for which we get the uses.

Return type:

Set[CodeLocation]

get_uses_with_expr(definition)

Retrieve the uses and the corresponding expressions of a given definition.

Parameters:

definition (Definition) – The definition for which we get the uses and the corresponding expressions.

Return type:

Set[Tuple[CodeLocation, Optional[Any]]]

remove_use(definition, codeloc, expr=None)

Remove one use of a given definition.

Parameters:

• definition (Definition) – The definition of which to remove the uses.

• codeloc (CodeLocation) – The code location where the use is.

• expr (Optional[Any]) – The expression that uses the definition at the given location.

Return type:

None

Returns:

None

remove_uses(definition)

Remove all uses of a given definition.

Parameters:

definition (Definition) – The definition of which to remove the uses.

Returns:

None

get_uses_by_location(codeloc, exprs=False)

Retrieve all definitions that are used at a given location.

Parameters:

• codeloc (CodeLocation) – The code location.

• exprs (bool) –

Return type:

Union[Set[Definition], Set[Tuple[Definition, Optional[Any]]]]

Returns:

A set of definitions that are used at the given location.

get_uses_by_insaddr(ins_addr, exprs=False)

Retrieve all definitions that are used at a given location specified by the instruction address.

Parameters:

• ins_addr (int) – The instruction address.

• exprs (bool) –

Return type:

Union[Set[Definition], Set[Tuple[Definition, Optional[Any]]]]

Returns:

A set of definitions that are used at the given location.

copy()

Copy the instance.

Return type:

Uses

Returns:

Return a new <Uses> instance containing the same data.

merge(other)

Merge an instance of <Uses> into the current instance.

Parameters:

other (Uses) – The other <Uses> from which the data will be added to the current instance.

Return type:

bool

Returns:

True if any merge occurred, False otherwise

angr.knowledge_plugins.sync.sync_controller.import_binsync()

angr.knowledge_plugins.sync.sync_controller.make_state(f)

Build a writeable State instance and pass to f as the state kwarg if the state kwarg is None. Function f should have have at least two kwargs, user and state.

angr.knowledge_plugins.sync.sync_controller.make_ro_state(f)

Build a read-only State instance and pass to f as the state kwarg if the state kwarg is None. Function f should have have at least two kwargs, user and state.

angr.knowledge_plugins.sync.sync_controller.init_checker(f)

class angr.knowledge_plugins.sync.sync_controller.SyncController(kb)

Bases: KnowledgeBasePlugin

SyncController interfaces with a binsync client to push changes upwards and pull changes downwards.

Variables:

client (binsync.Client) – The binsync client.

__init__(kb)

connect(user, path, bin_hash='', init_repo=False, ssh_agent_pid=None, ssh_auth_sock=None, remote_url=None)

property connected

commit()

update()

copy()

pull()

property has_remote

users()

status()

tally(users=None)

push_function(func, user=None, state=None)

Push a function upwards.

Parameters:

func (Function) – The angr Function object to push upwards.

Returns:

True if updates are made. False otherwise.

Return type:

bool

push_comment(addr, comment, decompiled=False, user=None, state=None)

push_comments(comments, user=None, state=None)

Push a bunch of comments upwards.

Parameters:

comments (list) – A list of BinSync Comments

Returns:

bool

push_stack_variables(stack_variables, var_manager, user=None, state=None)

Parameters:

• stack_variables (List[SimStackVariable]) –

• var_manager (VariableManagerInternal) –

Returns:

push_stack_variable(func_addr, offset, name, type_, size_, user=None, state=None)

pull_function(addr, user=None, state=None)

Pull a function downwards.

Parameters:

• addr (int) – Address of the function.

• user (str) – Name of the user.

Returns:

The binsync.data.Function object if pulling succeeds, or None if pulling fails.

Return type:

binsync.data.Function | None

pull_comment(addr, user=None, state=None)

Pull a comment downwards.

Parameters:

• addr (int) – Address of the comment.

• user (str) – Name of the user.

Returns:

a Comment object from BinSync, or None

Return type:

binsync.data.Comment | None

pull_comments(func_addr, user=None, state=None)

Pull comments downwards.

Parameters:

• start_addr (int) – Where we want to pull comments.

• end_addr (int) – Where we want to stop pulling comments (exclusive).

Returns:

An iterator.

Return type:

Iterable

pull_patches(user=None, state=None)

Pull patches.

Parameters:

user (str) – Name of the user to patches from.

Returns:

An iterator

Return type:

Iterable

pull_stack_variables(func_addr, user=None, state=None)

Pull stack variables from a function.

@param func_addr: Function address to pull from @param user: @param state: @return:

get_func_addr_from_addr(addr)

static register_default(name, cls)

class angr.knowledge_plugins.xrefs.xref.XRef(ins_addr=None, block_addr=None, stmt_idx=None, insn_op_idx=None, memory_data=None, dst=None, xref_type=None)

Bases: Serializable

XRef describes a reference to a MemoryData instance (if a MemoryData instance is available) or just an address.

Parameters:

• ins_addr (int | None) –

• block_addr (int | None) –

• stmt_idx (int | None) –

• insn_op_idx (int | None) –

• dst (int | None) –

__init__(ins_addr=None, block_addr=None, stmt_idx=None, insn_op_idx=None, memory_data=None, dst=None, xref_type=None)

Parameters:

• ins_addr (int | None) –

• block_addr (int | None) –

• stmt_idx (int | None) –

• insn_op_idx (int | None) –

• dst (int | None) –

ins_addr: Optional[int]

insn_op_idx: Optional[int]

block_addr: Optional[int]

stmt_idx: Optional[int]

memory_data

type

dst

property type_string

serialize_to_cmessage()

Serialize the class object and returns a protobuf cmessage object.

Returns:

A protobuf cmessage object.

Return type:

protobuf.cmessage

classmethod parse_from_cmessage(cmsg, bits=None, **kwargs)

Parse a protobuf cmessage and create a class object.

Parameters:

cmsg – The probobuf cmessage object.

Returns:

A unserialized class object.

Return type:

cls

copy()

insn_op_type

classmethod parse(s, **kwargs)

Parse a bytes object and create a class object.

Parameters:

s (bytes) – A bytes object.

Returns:

A class object.

Return type:

cls

serialize()

Serialize the class object and returns a bytes object.

Returns:

A bytes object.

Return type:

bytes

class angr.knowledge_plugins.xrefs.xref_types.XRefType

Bases: object

Offset = 0

Read = 1

Write = 2

static to_string(ty)

class angr.knowledge_plugins.xrefs.xref_manager.XRefManager(kb)

Bases: KnowledgeBasePlugin, Serializable

__init__(kb)

copy()

add_xref(xref)

add_xrefs(xrefs)

get_xrefs_by_ins_addr(ins_addr)

get_xrefs_by_dst(dst)

get_xrefs_by_dst_region(start, end)

Get a set of XRef objects that point to a given address region bounded by start and end. Will only return absolute xrefs, not relative ones (like SP offsets)

get_xrefs_by_ins_addr_region(start, end)

Get a set of XRef objects that originate at a given address region bounded by start and end. Useful for finding references from a basic block or function.

Return type:

Set[XRef]

serialize_to_cmessage()

Serialize the class object and returns a protobuf cmessage object.

Returns:

A protobuf cmessage object.

Return type:

protobuf.cmessage

classmethod parse_from_cmessage(cmsg, cfg_model=None, kb=None, **kwargs)

Parse a protobuf cmessage and create a class object.

Parameters:

cmsg – The probobuf cmessage object.

Returns:

A unserialized class object.

Return type:

cls

classmethod parse(s, **kwargs)

Parse a bytes object and create a class object.

Parameters:

s (bytes) – A bytes object.

Returns:

A class object.

Return type:

cls

static register_default(name, cls)

serialize()

Serialize the class object and returns a bytes object.

Returns:

A bytes object.

Return type:

bytes

class angr.code_location.CodeLocation(block_addr, stmt_idx, sim_procedure=None, ins_addr=None, context=None, block_idx=None, **kwargs)

Bases: object

Stands for a specific program point by specifying basic block address and statement ID (for IRSBs), or SimProcedure name (for SimProcedures).

Parameters:

• block_addr (int) –

• stmt_idx (int | None) –

• ins_addr (int | None) –

• context (Any) –

• block_idx (int) –

__init__(block_addr, stmt_idx, sim_procedure=None, ins_addr=None, context=None, block_idx=None, **kwargs)

Constructor.

Parameters:

• block_addr (int) – Address of the block

• stmt_idx (Optional[int]) – Statement ID. None for SimProcedures or if the code location is meant to refer to the entire block.

• sim_procedure (class) – The corresponding SimProcedure class.

• ins_addr (Optional[int]) – The instruction address.

• context (Optional[Any]) – A tuple that represents the context of this CodeLocation in contextful mode, or None in contextless mode.

• kwargs – Optional arguments, will be stored, but not used in __eq__ or __hash__.

• block_idx (int | None) –

block_addr: int

stmt_idx: Optional[int]

sim_procedure

ins_addr: Optional[int]

context: Optional[Tuple[int]]

block_idx

info: Optional[Dict]

property short_repr

class angr.keyed_region.StoredObject(start, obj, size)

Bases: object

__init__(start, obj, size)

start

obj

size: Union[UnknownSize, int]

property obj_id

class angr.keyed_region.RegionObject(start, size, objects=None)

Bases: object

Represents one or more objects occupying one or more bytes in KeyedRegion.

__init__(start, size, objects=None)

start

size

stored_objects

property is_empty

property end

property internal_objects

includes(offset)

split(split_at)

add_object(obj)

set_object(obj)

copy()

class angr.keyed_region.KeyedRegion(tree=None, phi_node_contains=None, canonical_size=8)

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.

__init__(tree=None, phi_node_contains=None, canonical_size=8)

copy()

merge(other, replacements=None)

Merge another KeyedRegion into this KeyedRegion.

Parameters:

other (KeyedRegion) – The other instance to merge with.

Returns:

None

merge_to_top(other, replacements=None, top=None)

Merge another KeyedRegion into this KeyedRegion, but mark all variables with different values as TOP.

Parameters:

• other – The other instance to merge with.

• replacements –

Returns:

self

replace(replacements)

Replace variables with other variables.

Parameters:

replacements (dict) – A dict of variable replacements.

Returns:

self

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:

• start (int) –

• variable (SimVariable) –

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:

• start (int) –

• variable (SimVariable) –

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 set of variables.

Return type:

set

get_objects_by_offset(start)

Find objects covering the given region offset.

Parameters:

start –

Returns:

get_all_variables()

Get all variables covering the current region.

Returns:

A set of all variables.

Serialization

class angr.serializable.Serializable

Bases: object

The base class of all protobuf-serializable classes in angr.

serialize_to_cmessage()

Serialize the class object and returns a protobuf cmessage object.

Returns:

A protobuf cmessage object.

Return type:

protobuf.cmessage

serialize()

Serialize the class object and returns a bytes object.

Returns:

A bytes object.

Return type:

bytes

classmethod parse_from_cmessage(cmsg, **kwargs)

Parse a protobuf cmessage and create a class object.

Parameters:

cmsg – The probobuf cmessage object.

Returns:

A unserialized class object.

Return type:

cls

classmethod parse(s, **kwargs)

Parse a bytes object and create a class object.

Parameters:

s (bytes) – A bytes object.

Returns:

A class object.

Return type:

cls

class angr.vaults.VaultPickler(vault, file, *args, assigned_objects=(), **kwargs)

Bases: Pickler

__init__(vault, file, *args, assigned_objects=(), **kwargs)

A persistence-aware pickler. It will check for persistence of any objects except for those with IDs in ‘assigned_objects’.

persistent_id(obj)

bin

clear_memo()

Clears the pickler’s “memo”.

The memo is the data structure that remembers which objects the pickler has already seen, so that shared or recursive objects are pickled by reference and not by value. This method is useful when re-using picklers.

dispatch_table

dump(obj, /)

Write a pickled representation of the given object to the open file.

fast

memo

class angr.vaults.VaultUnpickler(vault, file, *args, **kwargs)

Bases: Unpickler

__init__(vault, file, *args, **kwargs)

persistent_load(pid)

find_class(module_name, global_name, /)

Return an object from a specified module.

If necessary, the module will be imported. Subclasses may override this method (e.g. to restrict unpickling of arbitrary classes and functions).

This method is called whenever a class or a function object is needed. Both arguments passed are str objects.

load()

Load a pickle.

Read a pickled object representation from the open file object given in the constructor, and return the reconstituted object hierarchy specified therein.

memo

class angr.vaults.Vault

Bases: MutableMapping

The vault is a serializer for angr.

keys()

Should return the IDs stored by the vault.

__init__()

is_stored(i)

Checks if the provided id is already in the vault.

load(oid)

store(o)

dumps(o)

Returns a serialized string representing the object, post-deduplication.

Parameters:

o – the object

loads(s)

Deserializes a string representation of the object.

Parameters:

s – the string

static close()

clear() → None.  Remove all items from D.

get(k[, d]) → D[k] if k in D, else d.  d defaults to None.

items() → a set-like object providing a view on D's items

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

update([E, ]**F) → None.  Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → an object providing a view on D's values

class angr.vaults.VaultDict(d=None)

Bases: Vault

A Vault that uses a dictionary for storage.

__init__(d=None)

is_stored(i)

Checks if the provided id is already in the vault.

keys()

Should return the IDs stored by the vault.

clear() → None.  Remove all items from D.

static close()

dumps(o)

Returns a serialized string representing the object, post-deduplication.

Parameters:

o – the object

get(k[, d]) → D[k] if k in D, else d.  d defaults to None.

items() → a set-like object providing a view on D's items

load(oid)

loads(s)

Deserializes a string representation of the object.

Parameters:

s – the string

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

store(o)

update([E, ]**F) → None.  Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → an object providing a view on D's values

class angr.vaults.VaultDir(d=None)

Bases: Vault

A Vault that uses a directory for storage.

__init__(d=None)

keys()

Should return the IDs stored by the vault.

clear() → None.  Remove all items from D.

static close()

dumps(o)

Returns a serialized string representing the object, post-deduplication.

Parameters:

o – the object

get(k[, d]) → D[k] if k in D, else d.  d defaults to None.

is_stored(i)

Checks if the provided id is already in the vault.

items() → a set-like object providing a view on D's items

load(oid)

loads(s)

Deserializes a string representation of the object.

Parameters:

s – the string

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

store(o)

update([E, ]**F) → None.  Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → an object providing a view on D's values

class angr.vaults.VaultShelf(path=None)

Bases: VaultDict

A Vault that uses a shelve.Shelf for storage.

__init__(path=None)

close()

clear() → None.  Remove all items from D.

dumps(o)

Returns a serialized string representing the object, post-deduplication.

Parameters:

o – the object

get(k[, d]) → D[k] if k in D, else d.  d defaults to None.

is_stored(i)

Checks if the provided id is already in the vault.

items() → a set-like object providing a view on D's items

keys()

Should return the IDs stored by the vault.

load(oid)

loads(s)

Deserializes a string representation of the object.

Parameters:

s – the string

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

store(o)

update([E, ]**F) → None.  Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → an object providing a view on D's values

class angr.vaults.VaultDirShelf(d=None)

Bases: VaultDict

A Vault that uses a directory for storage, where every object is stored into a single shelve.Shelf instance. VaultDir creates a file for each object. VaultDirShelf creates only one file for a stored object and everything else it references.

__init__(d=None)

store(o)

load(oid)

keys()

Should return the IDs stored by the vault.

clear() → None.  Remove all items from D.

static close()

dumps(o)

Returns a serialized string representing the object, post-deduplication.

Parameters:

o – the object

get(k[, d]) → D[k] if k in D, else d.  d defaults to None.

is_stored(i)

Checks if the provided id is already in the vault.

items() → a set-like object providing a view on D's items

loads(s)

Deserializes a string representation of the object.

Parameters:

s – the string

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

update([E, ]**F) → None.  Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → an object providing a view on D's values

Analysis

angr.analyses.register_analysis(cls, name)

class angr.analyses.analysis.AnalysisLogEntry(message, exc_info=False)

Bases: object

__init__(message, exc_info=False)

class angr.analyses.analysis.AnalysesHub(project)

Bases: PluginVendor[A]

This class contains functions for all the registered and runnable analyses,

__init__(project)

reload_analyses(**kwargs)

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.

Return type:

TypeVar(P)

Parameters:

name (str) –

has_plugin(name)

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

property has_plugin_preset: bool

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

property plugin_preset

Get the current active plugin preset

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

register_plugin(name, plugin)

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

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.

release_plugin(name)

Deactivate and remove the plugin with name name.

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.

class angr.analyses.analysis.KnownAnalysesPlugin(*args, **kwargs)

Bases: Protocol

Identifier: Type[Identifier]

CalleeCleanupFinder: Type[CalleeCleanupFinder]

VSA_DDG: Type[VSA_DDG]

CDG: Type[CDG]

BinDiff: Type[BinDiff]

CFGEmulated: Type[CFGEmulated]

CFB: Type[CFBlanket]

CFBlanket: Type[CFBlanket]

CFG: Type[CFG]

CFGFast: Type[CFGFast]

StaticHooker: Type[StaticHooker]

DDG: Type[DDG]

CongruencyCheck: Type[CongruencyCheck]

Reassembler: Type[Reassembler]

BackwardSlice: Type[BackwardSlice]

BinaryOptimizer: Type[BinaryOptimizer]

VFG: Type[VFG]

LoopFinder: Type[LoopFinder]

Disassembly: Type[Disassembly]

Veritesting: Type[Veritesting]

CodeTagging: Type[CodeTagging]

BoyScout: Type[BoyScout]

VariableRecoveryFast: Type[VariableRecoveryFast]

VariableRecovery: Type[VariableRecovery]

ReachingDefinitions: Type[ReachingDefinitionsAnalysis]

CompleteCallingConventions: Type[CompleteCallingConventionsAnalysis]

Clinic: Type[Clinic]

Propagator: Type[PropagatorAnalysis]

CallingConvention: Type[CallingConventionAnalysis]

Decompiler: Type[Decompiler]

XRefs: Type[XRefsAnalysis]

__init__(*args, **kwargs)

class angr.analyses.analysis.AnalysesHubWithDefault(project)

Bases: AnalysesHub, KnownAnalysesPlugin

This class has type-hinting for all built-in analyses plugin

__init__(project)

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.

Return type:

TypeVar(P)

Parameters:

name (str) –

has_plugin(name)

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

property has_plugin_preset: bool

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

property plugin_preset

Get the current active plugin preset

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

register_plugin(name, plugin)

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

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.

release_plugin(name)

Deactivate and remove the plugin with name name.

reload_analyses(**kwargs)

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.

Identifier: Type[Identifier]

CalleeCleanupFinder: Type[CalleeCleanupFinder]

VSA_DDG: Type[VSA_DDG]

CDG: Type[CDG]

BinDiff: Type[BinDiff]

CFGEmulated: Type[CFGEmulated]

CFB: Type[CFBlanket]

CFBlanket: Type[CFBlanket]

CFG: Type[CFG]

CFGFast: Type[CFGFast]

StaticHooker: Type[StaticHooker]

DDG: Type[DDG]

CongruencyCheck: Type[CongruencyCheck]

Reassembler: Type[Reassembler]

BackwardSlice: Type[BackwardSlice]

BinaryOptimizer: Type[BinaryOptimizer]

VFG: Type[VFG]

LoopFinder: Type[LoopFinder]

Disassembly: Type[Disassembly]

Veritesting: Type[Veritesting]

CodeTagging: Type[CodeTagging]

BoyScout: Type[BoyScout]

VariableRecoveryFast: Type[VariableRecoveryFast]

VariableRecovery: Type[VariableRecovery]

ReachingDefinitions: Type[ReachingDefinitionsAnalysis]

CompleteCallingConventions: Type[CompleteCallingConventionsAnalysis]

Clinic: Type[Clinic]

Propagator: Type[PropagatorAnalysis]

CallingConvention: Type[CallingConventionAnalysis]

Decompiler: Type[Decompiler]

XRefs: Type[XRefsAnalysis]

class angr.analyses.analysis.AnalysisFactory(project, analysis_cls)

Bases: Generic[A]

__init__(project, analysis_cls)

Parameters:

• project (Project) –

• analysis_cls (Type[A]) –

prep(fail_fast=False, kb=None, progress_callback=None, show_progressbar=False)

Return type:

Type[TypeVar(A, bound= Analysis)]

Parameters:

• kb (KnowledgeBase | None) –

• progress_callback (Callable | None) –

• show_progressbar (bool) –

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 (progress.Progress) – The progress bar object.

project: Project

kb: KnowledgeBase

errors = []

named_errors = {}

class angr.analyses.forward_analysis.forward_analysis.ForwardAnalysis(order_jobs=False, allow_merging=False, allow_widening=False, status_callback=None, graph_visitor=None)

Bases: Generic[AnalysisState, NodeType, JobType, JobKey]

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.

__init__(order_jobs=False, allow_merging=False, allow_widening=False, status_callback=None, graph_visitor=None)

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.

• status_callback (Callable[[Type[ForwardAnalysis]], Any] | None) –

Returns:

None

property should_abort

Should the analysis be terminated. :return: True/False

property graph: DiGraph

property jobs

abort()

Abort the analysis :return: None

has_job(job)

Checks whether there exists another job which has the same job key. :type job: TypeVar(JobType) :param job: The job to check.

Return type:

bool

Returns:

True if there exists another job with the same key, False otherwise.

Parameters:

job (JobType) –

downsize()

class angr.analyses.forward_analysis.job_info.JobInfo(key, job)

Bases: Generic[JobType, JobKey]

Stores information of each job.

__init__(key, job)

Parameters:

• key (JobKey) –

• job (JobType) –

property job: JobType

Get the latest available job.

Returns:

The latest available job.

property merged_jobs

property widened_jobs

add_job(job, merged=False, widened=False)

Appended a new job to this JobInfo node. :type job: :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.visitors.call_graph.CallGraphVisitor(callgraph)

Bases: GraphVisitor

Parameters:

callgraph (networkx.DiGraph) –

__init__(callgraph)

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.

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.

all_successors(node, skip_reached_fixedpoint=False)

Returns all successors to the specific node.

Parameters:

node (TypeVar(NodeType)) – A node in the graph.

Returns:

A set of nodes that are all successors to the given node.

Return type:

set

back_edges()

Get a list of back edges. This function is optional. If not overriden, the traverser cannot achieve an optimal graph traversal order.

Return type:

List[Tuple[TypeVar(NodeType), TypeVar(NodeType)]]

Returns:

A list of back edges (source -> destination).

next_node()

Get the next node to visit.

Return type:

Optional[TypeVar(NodeType)]

Returns:

A node in the graph.

nodes()

Return an iterator of nodes following an optimal traversal order.

Return type:

Iterator[TypeVar(NodeType)]

Returns:

nodes_iter(**kwargs)

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 (TypeVar(NodeType)) – The node to mark as reached fixed-point.

Return type:

None

Returns:

None

reset()

Reset the internal node traversal state. Must be called prior to visiting future nodes.

Returns:

None

revisit_node(node)

Revisit a node in the future. Do not include its successors immediately.

Parameters:

node (TypeVar(NodeType)) – The node to revisit in the future.

Return type:

None

Returns:

None

revisit_successors(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 (TypeVar(NodeType)) – The node to revisit in the future.

Return type:

None

Returns:

None

class angr.analyses.forward_analysis.visitors.function_graph.FunctionGraphVisitor(func, graph=None)

Bases: GraphVisitor

Parameters:

func (knowledge.Function) –

__init__(func, graph=None)

resume_with_new_graph(graph)

We can only reasonably reuse existing results if the node index of the already traversed nodes are the same as the ones from the new graph. Otherwise, we always restart.

Return type:

bool

Returns:

True if we are resuming, False if reset() is called.

Parameters:

graph (DiGraph) –

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.

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.

all_successors(node, skip_reached_fixedpoint=False)

Returns all successors to the specific node.

Parameters:

node (TypeVar(NodeType)) – A node in the graph.

Returns:

A set of nodes that are all successors to the given node.

Return type:

set

back_edges()

Get a list of back edges. This function is optional. If not overriden, the traverser cannot achieve an optimal graph traversal order.

Return type:

List[Tuple[TypeVar(NodeType), TypeVar(NodeType)]]

Returns:

A list of back edges (source -> destination).

next_node()

Get the next node to visit.

Return type:

Optional[TypeVar(NodeType)]

Returns:

A node in the graph.

nodes()

Return an iterator of nodes following an optimal traversal order.

Return type:

Iterator[TypeVar(NodeType)]

Returns:

nodes_iter(**kwargs)

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 (TypeVar(NodeType)) – The node to mark as reached fixed-point.

Return type:

None

Returns:

None

reset()

Reset the internal node traversal state. Must be called prior to visiting future nodes.

Returns:

None

revisit_node(node)

Revisit a node in the future. Do not include its successors immediately.

Parameters:

node (TypeVar(NodeType)) – The node to revisit in the future.

Return type:

None

Returns:

None

revisit_successors(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 (TypeVar(NodeType)) – The node to revisit in the future.

Return type:

None

Returns:

None

class angr.analyses.forward_analysis.visitors.graph.GraphVisitor

Bases: Generic[NodeType]

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.

__init__()

successors(node)

Get successors of a node. The node should be in the graph.

Parameters:

node (TypeVar(NodeType)) – 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 (TypeVar(NodeType)) – The node to work with.

Return type:

List[TypeVar(NodeType)]

Returns:

A list of predecessors.

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.

Return type:

List[TypeVar(NodeType)]

Returns:

A list of sorted nodes.

back_edges()

Get a list of back edges. This function is optional. If not overriden, the traverser cannot achieve an optimal graph traversal order.

Return type:

List[Tuple[TypeVar(NodeType), TypeVar(NodeType)]]

Returns:

A list of back edges (source -> destination).

nodes()

Return an iterator of nodes following an optimal traversal order.

Return type:

Iterator[TypeVar(NodeType)]

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.

Return type:

Optional[TypeVar(NodeType)]

Returns:

A node in the graph.

all_successors(node, skip_reached_fixedpoint=False)

Returns all successors to the specific node.

Parameters:

node (TypeVar(NodeType)) – A node in the graph.

Returns:

A set of nodes that are all successors to the given node.

Return type:

set

revisit_successors(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 (TypeVar(NodeType)) – The node to revisit in the future.

Return type:

None

Returns:

None

revisit_node(node)

Revisit a node in the future. Do not include its successors immediately.

Parameters:

node (TypeVar(NodeType)) – The node to revisit in the future.

Return type:

None

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 (TypeVar(NodeType)) – The node to mark as reached fixed-point.

Return type:

None

Returns:

None

class angr.analyses.forward_analysis.visitors.loop.LoopVisitor(loop)

Bases: GraphVisitor

Parameters:

loop (angr.analyses.loopfinder.Loop) – The loop to visit.

__init__(loop)

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.

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.

all_successors(node, skip_reached_fixedpoint=False)

Returns all successors to the specific node.

Parameters:

node (TypeVar(NodeType)) – A node in the graph.

Returns:

A set of nodes that are all successors to the given node.

Return type:

set

back_edges()

Get a list of back edges. This function is optional. If not overriden, the traverser cannot achieve an optimal graph traversal order.

Return type:

List[Tuple[TypeVar(NodeType), TypeVar(NodeType)]]

Returns:

A list of back edges (source -> destination).

next_node()

Get the next node to visit.

Return type:

Optional[TypeVar(NodeType)]

Returns:

A node in the graph.

nodes()

Return an iterator of nodes following an optimal traversal order.

Return type:

Iterator[TypeVar(NodeType)]

Returns:

nodes_iter(**kwargs)

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 (TypeVar(NodeType)) – The node to mark as reached fixed-point.

Return type:

None

Returns:

None

reset()

Reset the internal node traversal state. Must be called prior to visiting future nodes.

Returns:

None

revisit_node(node)

Revisit a node in the future. Do not include its successors immediately.

Parameters:

node (TypeVar(NodeType)) – The node to revisit in the future.

Return type:

None

Returns:

None

revisit_successors(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 (TypeVar(NodeType)) – The node to revisit in the future.

Return type:

None

Returns:

None

class angr.analyses.forward_analysis.visitors.single_node_graph.SingleNodeGraphVisitor(node)

Bases: GraphVisitor

Parameters:

node – The single node that should be in the graph.

__init__(node)

node

node_returned

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.

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.

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.

all_successors(node, skip_reached_fixedpoint=False)

Returns all successors to the specific node.

Parameters:

node (TypeVar(NodeType)) – A node in the graph.

Returns:

A set of nodes that are all successors to the given node.

Return type:

set

back_edges()

Get a list of back edges. This function is optional. If not overriden, the traverser cannot achieve an optimal graph traversal order.

Return type:

List[Tuple[TypeVar(NodeType), TypeVar(NodeType)]]

Returns:

A list of back edges (source -> destination).

nodes()

Return an iterator of nodes following an optimal traversal order.

Return type:

Iterator[TypeVar(NodeType)]

Returns:

nodes_iter(**kwargs)

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 (TypeVar(NodeType)) – The node to mark as reached fixed-point.

Return type:

None

Returns:

None

revisit_node(node)

Revisit a node in the future. Do not include its successors immediately.

Parameters:

node (TypeVar(NodeType)) – The node to revisit in the future.

Return type:

None

Returns:

None

revisit_successors(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 (TypeVar(NodeType)) – The node to revisit in the future.

Return type:

None

Returns:

None

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: Analysis

Represents a backward slice of the program.

__init__(cfg, cdg, ddg, targets=None, cfg_node=None, stmt_id=None, control_flow_slice=False, same_function=False, no_construct=False)

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.

is_taint_related_to_ip(simrun_addr, stmt_idx, taint_type, simrun_whitelist=None)

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.

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

exception angr.analyses.bindiff.UnmatchedStatementsException

Bases: Exception

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class angr.analyses.bindiff.Difference(diff_type, value_a, value_b)

Bases: object

__init__(diff_type, value_a, value_b)

class angr.analyses.bindiff.ConstantChange(offset, value_a, value_b)

Bases: object

__init__(offset, value_a, value_b)

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

__init__(block, function)

class angr.analyses.bindiff.NormalizedFunction(function)

Bases: object

Parameters:

function (Function) –

__init__(function)

Parameters:

function (Function) –

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 (Function) –

• function_b (Function) –

__init__(function_a, function_b, bindiff=None)

Parameters:

• function_a (Function) – The first angr Function object to diff.

• function_b (Function) – The second angr Function object.

• bindiff – An optional Bindiff object. Used for some extra normalization during basic block comparison.

property probably_identical

Whether or not these two functions are identical.

Type:

returns

property identical_blocks

A list of block matches which appear to be identical

Type:

returns

property differing_blocks

A list of block matches which appear to differ

Type:

returns

property blocks_with_differing_constants

A list of block matches which appear to differ

Type:

return

property block_matches

property 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: Analysis

This class computes the a diff between two binaries represented by angr Projects

__init__(other_project, enable_advanced_backward_slicing=False, cfg_a=None, cfg_b=None)

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.

property identical_functions

A list of function matches that appear to be identical

Type:

returns

property 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

property differing_blocks

A list of block matches that appear to differ

Type:

returns

property identical_blocks

return A list of all block matches that appear to be identical

property blocks_with_differing_constants

A dict of block matches with differing constants to the tuple of constants

Type:

return

property 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

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

class angr.analyses.boyscout.BoyScout(cookiesize=1)

Bases: Analysis

Try to determine the architecture and endieness of a binary blob

__init__(cookiesize=1)

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

class angr.analyses.calling_convention.CallSiteFact(return_value_used)

Bases: object

Store facts about each call site.

__init__(return_value_used)

class angr.analyses.calling_convention.UpdateArgumentsOption

Bases: object

Enums for controlling the argument updating behavior in _adjust_cc.

DoNotUpdate = 0

AlwaysUpdate = 1

UpdateWhenCCHasNoArgs = 2

class angr.analyses.calling_convention.CallingConventionAnalysis(func, cfg=None, analyze_callsites=False, caller_func_addr=None, callsite_block_addr=None, callsite_insn_addr=None, func_graph=None)

Bases: Analysis

Analyze the calling convention of a function and guess a probable prototype.

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.

Variables:

• _function – The function to recover calling convention for.

• _variable_manager – A handy accessor to the variable manager.

• _cfg – A reference of the CFGModel of the current binary. It is used to discover call sites of the current function in order to perform analysis at call sites.

• analyze_callsites – True if we should analyze all call sites of the current function to determine the calling convention and arguments. This can be time-consuming if there are many call sites to analyze.

• cc – The recovered calling convention for the function.

Parameters:

• func (Function | int | str | None) –

• cfg (CFGModel | None) –

• analyze_callsites (bool) –

• caller_func_addr (int | None) –

• callsite_block_addr (int | None) –

• callsite_insn_addr (int | None) –

• func_graph (DiGraph | None) –

__init__(func, cfg=None, analyze_callsites=False, caller_func_addr=None, callsite_block_addr=None, callsite_insn_addr=None, func_graph=None)

Parameters:

• func (Function | int | str | None) –

• cfg (CFGModel | None) –

• analyze_callsites (bool) –

• caller_func_addr (int | None) –

• callsite_block_addr (int | None) –

• callsite_insn_addr (int | None) –

• func_graph (DiGraph | None) –

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

class angr.analyses.complete_calling_conventions.CompleteCallingConventionsAnalysis(recover_variables=False, low_priority=False, force=False, cfg=None, analyze_callsites=False, skip_signature_matched_functions=False, max_function_blocks=None, max_function_size=None, workers=0, cc_callback=None, prioritize_func_addrs=None, skip_other_funcs=False, auto_start=True, func_graphs=None)

Bases: Analysis

Implements full-binary calling convention analysis. During the initial analysis of a binary, you may set recover_variables to True so that it will perform variable recovery on each function before performing calling convention analysis.

Parameters:

• cfg (CFGModel | None) –

• analyze_callsites (bool) –

• skip_signature_matched_functions (bool) –

• max_function_blocks (int | None) –

• max_function_size (int | None) –

• workers (int) –

• cc_callback (Callable | None) –

• prioritize_func_addrs (Iterable[int] | None) –

• skip_other_funcs (bool) –

• auto_start (bool) –

• func_graphs (Dict[int, networkx.DiGraph] | None) –

__init__(recover_variables=False, low_priority=False, force=False, cfg=None, analyze_callsites=False, skip_signature_matched_functions=False, max_function_blocks=None, max_function_size=None, workers=0, cc_callback=None, prioritize_func_addrs=None, skip_other_funcs=False, auto_start=True, func_graphs=None)

Parameters:

• recover_variables – Recover variables on each function before performing calling convention analysis.

• low_priority – Run in the background - periodically release GIL.

• force – Perform calling convention analysis on functions even if they have calling conventions or prototypes already specified (or previously recovered).

• cfg (Optional[CFGModel]) – The control flow graph model, which will be passed to CallingConventionAnalysis.

• analyze_callsites (bool) – Consider artifacts at call sites when performing calling convention analysis.

• skip_signature_matched_functions (bool) – Do not perform calling convention analysis on functions that match against existing FLIRT signatures.

• max_function_blocks (Optional[int]) – Do not perform calling convention analysis on functions with more than the specified number of blocks. Setting it to None disables this check.

• max_function_size (Optional[int]) – Do not perform calling convention analysis on functions whose sizes are more than max_function_size. Setting it to None disables this check.

• workers (int) – Number of multiprocessing workers.

• cc_callback (Callable | None) –

• prioritize_func_addrs (Iterable[int] | None) –

• skip_other_funcs (bool) –

• auto_start (bool) –

• func_graphs (Dict[int, DiGraph] | None) –

work()

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

prioritize_functions(func_addrs_to_prioritize)

Prioritize the analysis of specified functions.

Parameters:

func_addrs_to_prioritize (Iterable[int]) – A collection of function addresses to analyze first.

static function_needs_variable_recovery(func)

Check if running variable recovery on the function is the only way to determine the calling convention of the this function.

We do not need to run variable recovery to determine the calling convention of a function if: - The function is a SimProcedure. - The function is a PLT stub. - The function is a library function and we already know its prototype.

Parameters:

func – The function object.

Returns:

True if we must run VariableRecovery before we can determine what the calling convention of this function is. False otherwise.

Return type:

bool

exception angr.analyses.soot_class_hierarchy.SootClassHierarchyError(msg)

Bases: Exception

__init__(msg)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.analyses.soot_class_hierarchy.NoConcreteDispatch(msg)

Bases: SootClassHierarchyError

__init__(msg)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class angr.analyses.soot_class_hierarchy.SootClassHierarchy

Bases: Analysis

Generate complete hierarchy.

__init__()

init_hierarchy()

has_super_class(cls)

is_subclass_including(cls_child, cls_parent)

is_subclass(cls_child, cls_parent)

is_visible_method(cls, method)

is_visible_class(cls_from, cls_to)

get_super_classes(cls)

get_super_classes_including(cls)

get_implementers(interface)

get_sub_interfaces_including(interface)

get_sub_interfaces(interface)

get_sub_classes(cls)

get_sub_classes_including(cls)

resolve_abstract_dispatch(cls, method)

resolve_concrete_dispatch(cls, method)

resolve_special_dispatch(method, container)

resolve_invoke(invoke_expr, method, container)

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

class angr.analyses.cfg.cfb.CFBlanketView(cfb)

Bases: object

A view into the control-flow blanket.

__init__(cfb)

class angr.analyses.cfg.cfb.MemoryRegion(addr, size, type_, object_, cle_region)

Bases: object

__init__(addr, size, type_, object_, cle_region)

class angr.analyses.cfg.cfb.Unknown(addr, size, bytes_=None, object_=None, segment=None, section=None)

Bases: object

__init__(addr, size, bytes_=None, object_=None, segment=None, section=None)

class angr.analyses.cfg.cfb.CFBlanket(exclude_region_types=None, on_object_added=None)

Bases: Analysis

A Control-Flow Blanket is a representation for storing all instructions, data entries, and bytes of a full program.

Region types: - section - segment - extern - tls - kernel

Parameters:

• exclude_region_types (Set[str] | None) –

• on_object_added (Callable[[int, Any], None] | None) –

__init__(exclude_region_types=None, on_object_added=None)

Parameters:

• on_object_added (Optional[Callable[[int, Any], None]]) – Callable with parameters (addr, obj) called after an object is added to the blanket.

• exclude_region_types (Set[str] | None) –

property regions

Return all memory regions.

floor_addr(addr)

floor_item(addr)

floor_items(addr=None, reverse=False)

ceiling_addr(addr)

ceiling_item(addr)

ceiling_items(addr=None, reverse=False, include_first=True)

add_obj(addr, obj)

Adds an object obj to the blanket at the specified address addr

add_function(func)

Add a function func and all blocks of this function to the blanket.

dbg_repr()

The debugging representation of this CFBlanket.

Returns:

The debugging representation of this CFBlanket.

Return type:

str

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

exception angr.analyses.cfg.cfg.OutdatedError

Bases: Exception

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class angr.analyses.cfg.cfg.CFG(**kwargs)

Bases: CFGFast

tl;dr: CFG is just a wrapper around CFGFast for compatibility issues. It will be fully replaced by CFGFast in future releases. Feel free to use CFG if you intend to use CFGFast. Please use CFGEmulated if you have to use the old, slow, dynamically-generated version of CFG.

For multiple historical reasons, angr’s CFG is accurate but slow, which does not meet what most people expect. We developed CFGFast for light-speed CFG recovery, and renamed the old CFG class to CFGEmulated. For compability concerns, CFG was kept as an alias to CFGEmulated.

However, so many new users of angr would load up a binary and generate a CFG immediately after running “pip install angr”, and draw the conclusion that “angr’s CFG is so slow - angr must be unusable!” Therefore, we made the hard decision: CFG will be an alias to CFGFast, instead of CFGEmulated.

To ease the transition of your existing code and script, the following changes are made:

• A CFG class, which is a sub class of CFGFast, is created.

• You will see both a warning message printed out to stderr and an exception raised by angr if you are passing CFG any parameter that only CFGEmulated supports. This exception is not a sub class of AngrError, so you wouldn’t capture it with your old code by mistake.

• In the near future, this wrapper class will be removed completely, and CFG will be a simple alias to CFGFast.

We expect most interfaces are the same between CFGFast and CFGEmulated. Apparently some functionalities (like context-sensitivity, and state keeping) only exist in CFGEmulated, which is when you want to use CFGEmulated instead.

__init__(**kwargs)

Parameters:

• binary – The binary to recover CFG on. By default the main binary is used.

• objects – A list of objects to recover the CFG on. By default it will recover the CFG of all loaded objects.

• regions (iterable) – A list of tuples in the form of (start address, end address) describing memory regions that the CFG should cover.

• pickle_intermediate_results (bool) – If we want to store the intermediate results or not.

• symbols (bool) – Get function beginnings from symbols in the binary.

• function_prologues (bool) – Scan the binary for function prologues, and use those positions as function beginnings

• resolve_indirect_jumps (bool) – Try to resolve indirect jumps. This is necessary to resolve jump targets from jump tables, etc.

• force_segment (bool) – Force CFGFast to rely on binary segments instead of sections.

• force_complete_scan (bool) – Perform a complete scan on the binary and maximize the number of identified code blocks.

• data_references (bool) – Enables the collection of references to data used by individual instructions. This does not collect ‘cross-references’, particularly those that involve multiple instructions. For that, see cross_references

• cross_references (bool) – Whether CFGFast should collect “cross-references” from the entire program or not. This will populate the knowledge base with references to and from each recognizable address constant found in the code. Note that, because this performs constant propagation on the entire program, it may be much slower and consume more memory. This option implies data_references=True.

• normalize (bool) – Normalize the CFG as well as all function graphs after CFG recovery.

• start_at_entry (bool) – Begin CFG recovery at the entry point of this project. Setting it to False prevents CFGFast from viewing the entry point as one of the starting points of code scanning.

• function_starts (list) – A list of extra function starting points. CFGFast will try to resume scanning from each address in the list.

• extra_memory_regions (list) – A list of 2-tuple (start-address, end-address) that shows extra memory regions. Integers falling inside will be considered as pointers.

• indirect_jump_resolvers (list) – A custom list of indirect jump resolvers. If this list is None or empty, default indirect jump resolvers specific to this architecture and binary types will be loaded.

• base_state – A state to use as a backer for all memory loads

• detect_tail_calls (bool) – Enable aggressive tail-call optimization detection.

• elf_eh_frame (bool) – Retrieve function starts (and maybe sizes later) from the .eh_frame of ELF binaries.

• skip_unmapped_addrs – Ignore all branches into unmapped regions. True by default. You may want to set it to False if you are analyzing manually patched binaries or malware samples.

• indirect_calls_always_return – Should CFG assume indirect calls must return or not. Assuming indirect calls must return will significantly reduce the number of constant propagation runs, but may reduce the overall CFG recovery precision when facing non-returning indirect calls. By default, we only assume indirect calls always return for large binaries (region > 50KB).

• jumptable_resolver_resolves_calls – Whether JumpTableResolver should resolve indirect calls or not. Most indirect calls in C++ binaries or UEFI binaries cannot be resolved using jump table resolver and must be resolved using their specific resolvers. By default, we will only disable JumpTableResolver from resolving indirect calls for large binaries (region > 50 KB).

• start (int) – (Deprecated) The beginning address of CFG recovery.

• end (int) – (Deprecated) The end address of CFG recovery.

• arch_options (CFGArchOptions) – Architecture-specific options.

• extra_arch_options (dict) – Any key-value pair in kwargs will be seen as an arch-specific option and will be used to set the option value in self._arch_options.

Extra parameters that angr.Analysis takes:

Parameters:

• progress_callback – Specify a callback function to get the progress during CFG recovery.

• show_progressbar (bool) – Should CFGFast show a progressbar during CFG recovery or not.

Returns:

None

PRINTABLES = b'0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~ \t\n\r'

SPECIAL_THUNKS = {'AMD64': {b'\xe8\x07\x00\x00\x00\xf3\x90\x0f\xae\xe8\xeb\xf9H\x89\x04$\xc3': ('jmp', 'rax'), b'\xe8\x07\x00\x00\x00\xf3\x90\x0f\xae\xe8\xeb\xf9H\x8dd$\x08\xc3': ('ret',)}}

abort()

Abort the analysis :return: None

property context_sensitivity_level

copy()

do_full_xrefs(overlay_state=None)

Perform xref recovery on all functions.

Parameters:

overlay (SimState) – An overlay state for loading constant data.

Returns:

None

downsize()

errors = []

property functions

A reference to the FunctionManager in the current knowledge base.

Returns:

FunctionManager with all functions

Return type:

angr.knowledge_plugins.FunctionManager

generate_code_cover(**kwargs)

generate_index()

Generate an index of all nodes in the graph in order to speed up get_any_node() with anyaddr=True.

Returns:

None

get_all_nodes(**kwargs)

get_all_predecessors(**kwargs)

get_all_successors(**kwargs)

get_any_node(**kwargs)

get_branching_nodes(**kwargs)

get_exit_stmt_idx(**kwargs)

get_loop_back_edges()

get_node(**kwargs)

get_predecessors(**kwargs)

get_successors(**kwargs)

get_successors_and_jumpkind(**kwargs)

property graph

has_job(job)

Checks whether there exists another job which has the same job key. :type job: TypeVar(JobType) :param job: The job to check.

Return type:

bool

Returns:

True if there exists another job with the same key, False otherwise.

Parameters:

job (JobType) –

property insn_addr_to_memory_data

is_thumb_addr(addr)

property jobs

property jump_tables

make_copy(copy_to)

Copy self attributes to the new object.

Parameters:

copy_to (CFGBase) – The target to copy to.

Returns:

None

make_functions()

Revisit the entire control flow graph, create Function instances accordingly, and correctly put blocks into each function.

Although Function objects are crated during the CFG recovery, they are neither sound nor accurate. With a pre-constructed CFG, this method rebuilds all functions bearing the following rules:

• A block may only belong to one function.

• Small functions lying inside the startpoint and the endpoint of another function will be merged with the other function

• Tail call optimizations are detected.

• PLT stubs are aligned by 16.

Returns:

None

mark_function_alignments()

Find all potential function alignments and mark them.

Note that it is not always correct to simply remove them, because these functions may not be actual alignments but part of an actual function, and is incorrectly marked as an individual function because of failures in resolving indirect jumps. An example is in the test binary x86_64/dir_gcc_-O0 0x40541d (indirect jump at 0x4051b0). If the indirect jump cannot be correctly resolved, removing function 0x40541d will cause a missing label failure in reassembler.

Returns:

None

property memory_data

property model: CFGModel

Get the CFGModel instance. :return: The CFGModel instance that this analysis currently uses.

named_errors = {}

nodes(**kwargs)

nodes_iter(**kwargs)

normalize()

Normalize the CFG, making sure that there are no overlapping basic blocks.

Note that this method will not alter transition graphs of each function in self.kb.functions. You may call normalize() on each Function object to normalize their transition graphs.

Returns:

None

property normalized

output()

remove_edge(block_from, block_to)

property should_abort

Should the analysis be terminated. :return: True/False

tag: Optional[str] = 'CFGFast'

project: Project

kb: KnowledgeBase

class angr.analyses.cfg.cfg_emulated.CFGJob(*args, **kwargs)

Bases: CFGJobBase

The job class that CFGEmulated uses.

__init__(*args, **kwargs)

property block_id

property is_syscall

property call_stack

call_stack_copy()

property current_stack_pointer

property func_addr

get_call_stack_suffix()

class angr.analyses.cfg.cfg_emulated.PendingJob(caller_func_addr, returning_source, state, src_block_id, src_exit_stmt_idx, src_exit_ins_addr, call_stack)

Bases: object

A PendingJob is whatever will be put into our pending_exit list. A pending exit is an entry that created by the returning of a call or syscall. It is “pending” since we cannot immediately figure out whether this entry will be executed or not. If the corresponding call/syscall intentially doesn’t return, then the pending exit will be removed. If the corresponding call/syscall returns, then the pending exit will be removed as well (since a real entry is created from the returning and will be analyzed later). If the corresponding call/syscall might return, but for some reason (for example, an unsupported instruction is met during the analysis) our analysis does not return properly, then the pending exit will be picked up and put into remaining_jobs list.

__init__(caller_func_addr, returning_source, state, src_block_id, src_exit_stmt_idx, src_exit_ins_addr, call_stack)

Parameters:

• returning_source – Address of the callee function. It might be None if address of the callee is not resolvable.

• state – The state after returning from the callee function. Of course there is no way to get a precise state without emulating the execution of the callee, but at least we can properly adjust the stack and registers to imitate the real returned state.

• call_stack – A callstack.

class angr.analyses.cfg.cfg_emulated.CFGEmulated(context_sensitivity_level=1, start=None, avoid_runs=None, enable_function_hints=False, call_depth=None, call_tracing_filter=None, initial_state=None, starts=None, keep_state=False, indirect_jump_target_limit=100000, resolve_indirect_jumps=True, enable_advanced_backward_slicing=False, enable_symbolic_back_traversal=False, indirect_jump_resolvers=None, additional_edges=None, no_construct=False, normalize=False, max_iterations=1, address_whitelist=None, base_graph=None, iropt_level=None, max_steps=None, state_add_options=None, state_remove_options=None, model=None)

Bases: ForwardAnalysis, CFGBase

This class represents a control-flow graph.

tag: Optional[str] = 'CFGEmulated'

__init__(context_sensitivity_level=1, start=None, avoid_runs=None, enable_function_hints=False, call_depth=None, call_tracing_filter=None, initial_state=None, starts=None, keep_state=False, indirect_jump_target_limit=100000, resolve_indirect_jumps=True, enable_advanced_backward_slicing=False, enable_symbolic_back_traversal=False, indirect_jump_resolvers=None, additional_edges=None, no_construct=False, normalize=False, max_iterations=1, address_whitelist=None, base_graph=None, iropt_level=None, max_steps=None, state_add_options=None, state_remove_options=None, model=None)

All parameters are optional.

Parameters:

• context_sensitivity_level – The level of context-sensitivity of this CFG (see documentation for further details). It ranges from 0 to infinity. Default 1.

• avoid_runs – A list of runs to avoid.

• enable_function_hints – Whether to use function hints (constants that might be used as exit targets) or not.

• call_depth – How deep in the call stack to trace.

• call_tracing_filter – Filter to apply on a given path and jumpkind to determine if it should be skipped when call_depth is reached.

• initial_state – An initial state to use to begin analysis.

• starts (iterable) – A collection of starting points to begin analysis. It can contain the following three different types of entries: an address specified as an integer, a 2-tuple that includes an integer address and a jumpkind, or a SimState instance. Unsupported entries in starts will lead to an AngrCFGError being raised.

• keep_state – Whether to keep the SimStates for each CFGNode.

• resolve_indirect_jumps – Whether to enable the indirect jump resolvers for resolving indirect jumps

• enable_advanced_backward_slicing – Whether to enable an intensive technique for resolving indirect jumps

• enable_symbolic_back_traversal – Whether to enable an intensive technique for resolving indirect jumps

• indirect_jump_resolvers (list) – A custom list of indirect jump resolvers. If this list is None or empty, default indirect jump resolvers specific to this architecture and binary types will be loaded.

• additional_edges – A dict mapping addresses of basic blocks to addresses of successors to manually include and analyze forward from.

• no_construct (bool) – Skip the construction procedure. Only used in unit-testing.

• normalize (bool) – If the CFG as well as all Function graphs should be normalized or not.

• max_iterations (int) – The maximum number of iterations that each basic block should be “executed”. 1 by default. Larger numbers of iterations are usually required for complex analyses like loop analysis.

• address_whitelist (iterable) – A list of allowed addresses. Any basic blocks outside of this collection of addresses will be ignored.

• base_graph (networkx.DiGraph) – A basic control flow graph to follow. Each node inside this graph must have the following properties: addr and size. CFG recovery will strictly follow nodes and edges shown in the graph, and discard any contorl flow that does not follow an existing edge in the base graph. For example, you can pass in a Function local transition graph as the base graph, and CFGEmulated will traverse nodes and edges and extract useful information.

• iropt_level (int) – The optimization level of VEX IR (0, 1, 2). The default level will be used if iropt_level is None.

• max_steps (int) – The maximum number of basic blocks to recover forthe longest path from each start before pausing the recovery procedure.

• state_add_options – State options that will be added to the initial state.

• state_remove_options – State options that will be removed from the initial state.

copy()

Make a copy of the CFG.

Return type:

CFGEmulated

Returns:

A copy of the CFG instance.

resume(starts=None, max_steps=None)

Resume a paused or terminated control flow graph recovery.

Parameters:

• starts (iterable) – A collection of new starts to resume from. If starts is None, we will resume CFG recovery from where it was paused before.

• max_steps (int) – The maximum number of blocks on the longest path starting from each start before pausing the recovery.

Returns:

None

remove_cycles()

Forces graph to become acyclic, removes all loop back edges and edges between overlapped loop headers and their successors.

downsize()

Remove saved states from all CFGNodes to reduce memory usage.

Returns:

None

unroll_loops(max_loop_unrolling_times)

Unroll loops for each function. The resulting CFG may still contain loops due to recursion, function calls, etc.

Parameters:

max_loop_unrolling_times (int) – The maximum iterations of unrolling.

Returns:

None

force_unroll_loops(max_loop_unrolling_times)

Unroll loops globally. The resulting CFG does not contain any loop, but this method is slow on large graphs.

Parameters:

max_loop_unrolling_times (int) – The maximum iterations of unrolling.

Returns:

None

immediate_dominators(start, target_graph=None)

Get all immediate dominators of sub graph from given node upwards.

Parameters:

• start (str) – id of the node to navigate forwards from.

• target_graph (networkx.classes.digraph.DiGraph) – graph to analyse, default is self.graph.

Returns:

each node of graph as index values, with element as respective node’s immediate dominator.

Return type:

dict

immediate_postdominators(end, target_graph=None)

Get all immediate postdominators of sub graph from given node upwards.

Parameters:

• start (str) – id of the node to navigate forwards from.

• target_graph (networkx.classes.digraph.DiGraph) – graph to analyse, default is self.graph.

Returns:

each node of graph as index values, with element as respective node’s immediate dominator.

Return type:

dict

remove_fakerets()

Get rid of fake returns (i.e., Ijk_FakeRet edges) from this CFG

Returns:

None

get_topological_order(cfg_node)

Get the topological order of a CFG Node.

Parameters:

cfg_node – A CFGNode instance.

Returns:

An integer representing its order, or None if the CFGNode does not exist in the graph.

get_subgraph(starting_node, block_addresses)

Get a sub-graph out of a bunch of basic block addresses.

Parameters:

• starting_node (CFGNode) – The beginning of the subgraph

• block_addresses (iterable) – A collection of block addresses that should be included in the subgraph if there is a path between starting_node and a CFGNode with the specified address, and all nodes on the path should also be included in the subgraph.

Returns:

A new CFG that only contain the specific subgraph.

Return type:

CFGEmulated

get_function_subgraph(start, max_call_depth=None)

Get a sub-graph of a certain function.

Parameters:

• start – The function start. Currently it should be an integer.

• max_call_depth – Call depth limit. None indicates no limit.

Returns:

A CFG instance which is a sub-graph of self.graph

property context_sensitivity_level

property graph

property unresolvables

Get those SimRuns that have non-resolvable exits.

Returns:

A set of SimRuns

Return type:

set

property deadends

Get all CFGNodes that has an out-degree of 0

Returns:

A list of CFGNode instances

Return type:

list

abort()

Abort the analysis :return: None

errors = []

property functions

A reference to the FunctionManager in the current knowledge base.

Returns:

FunctionManager with all functions

Return type:

angr.knowledge_plugins.FunctionManager

generate_index()

Generate an index of all nodes in the graph in order to speed up get_any_node() with anyaddr=True.

Returns:

None

get_all_nodes(**kwargs)

get_all_predecessors(**kwargs)

get_all_successors(**kwargs)

get_any_node(**kwargs)

get_branching_nodes(**kwargs)

get_exit_stmt_idx(**kwargs)

get_loop_back_edges()

get_node(**kwargs)

get_predecessors(**kwargs)

get_successors(**kwargs)

get_successors_and_jumpkind(**kwargs)

has_job(job)

Checks whether there exists another job which has the same job key. :type job: TypeVar(JobType) :param job: The job to check.

Return type:

bool

Returns:

True if there exists another job with the same key, False otherwise.

Parameters:

job (JobType) –

is_thumb_addr(addr)

property jobs

make_copy(copy_to)

Copy self attributes to the new object.

Parameters:

copy_to (CFGBase) – The target to copy to.

Returns:

None

make_functions()

Revisit the entire control flow graph, create Function instances accordingly, and correctly put blocks into each function.

Although Function objects are crated during the CFG recovery, they are neither sound nor accurate. With a pre-constructed CFG, this method rebuilds all functions bearing the following rules:

• A block may only belong to one function.

• Small functions lying inside the startpoint and the endpoint of another function will be merged with the other function

• Tail call optimizations are detected.

• PLT stubs are aligned by 16.

Returns:

None

mark_function_alignments()

Find all potential function alignments and mark them.

Note that it is not always correct to simply remove them, because these functions may not be actual alignments but part of an actual function, and is incorrectly marked as an individual function because of failures in resolving indirect jumps. An example is in the test binary x86_64/dir_gcc_-O0 0x40541d (indirect jump at 0x4051b0). If the indirect jump cannot be correctly resolved, removing function 0x40541d will cause a missing label failure in reassembler.

Returns:

None

property model: CFGModel

Get the CFGModel instance. :return: The CFGModel instance that this analysis currently uses.

named_errors = {}

nodes(**kwargs)

nodes_iter(**kwargs)

normalize()

Normalize the CFG, making sure that there are no overlapping basic blocks.

Note that this method will not alter transition graphs of each function in self.kb.functions. You may call normalize() on each Function object to normalize their transition graphs.

Returns:

None

property normalized

output()

remove_edge(block_from, block_to)

property should_abort

Should the analysis be terminated. :return: True/False

project: Project

kb: KnowledgeBase

class angr.analyses.cfg.cfg_base.CFGBase(sort, context_sensitivity_level, normalize=False, binary=None, objects=None, regions=None, exclude_sparse_regions=True, skip_specific_regions=True, force_segment=False, base_state=None, resolve_indirect_jumps=True, indirect_jump_resolvers=None, indirect_jump_target_limit=100000, detect_tail_calls=False, low_priority=False, skip_unmapped_addrs=True, sp_tracking_track_memory=True, model=None)

Bases: Analysis

The base class for control flow graphs.

tag: Optional[str] = None

__init__(sort, context_sensitivity_level, normalize=False, binary=None, objects=None, regions=None, exclude_sparse_regions=True, skip_specific_regions=True, force_segment=False, base_state=None, resolve_indirect_jumps=True, indirect_jump_resolvers=None, indirect_jump_target_limit=100000, detect_tail_calls=False, low_priority=False, skip_unmapped_addrs=True, sp_tracking_track_memory=True, model=None)

Parameters:

• sort (str) – ‘fast’ or ‘emulated’.

• context_sensitivity_level (int) – The level of context-sensitivity of this CFG (see documentation for further details). It ranges from 0 to infinity.

• normalize (bool) – Whether the CFG as well as all Function graphs should be normalized.

• binary (cle.backends.Backend) – The binary to recover CFG on. By default, the main binary is used.

• objects – A list of objects to recover the CFG on. By default, it will recover the CFG of all loaded objects.

• regions (iterable) – A list of tuples in the form of (start address, end address) describing memory regions that the CFG should cover.

• force_segment (bool) – Force CFGFast to rely on binary segments instead of sections.

• base_state (angr.SimState) – A state to use as a backer for all memory loads.

• resolve_indirect_jumps (bool) – Whether to try to resolve indirect jumps. This is necessary to resolve jump targets from jump tables, etc.

• indirect_jump_resolvers (list) – A custom list of indirect jump resolvers. If this list is None or empty, default indirect jump resolvers specific to this architecture and binary types will be loaded.

• indirect_jump_target_limit (int) – Maximum indirect jump targets to be recovered.

• skip_unmapped_addrs – Ignore all branches into unmapped regions. True by default. You may want to set it to False if you are analyzing manually patched binaries or malware samples.

• detect_tail_calls (bool) – Aggressive tail-call optimization detection. This option is only respected in make_functions().

• sp_tracking_track_memory (bool) – Whether or not to track memory writes if tracking the stack pointer. This increases the accuracy of stack pointer tracking, especially for architectures without a base pointer. Only used if detect_tail_calls is enabled.

• model (None or CFGModel) – The CFGModel instance to write to. A new CFGModel instance will be created and registered with the knowledge base if model is None.

Returns:

None

property model: CFGModel

Get the CFGModel instance. :return: The CFGModel instance that this analysis currently uses.

property normalized

property context_sensitivity_level

property functions

A reference to the FunctionManager in the current knowledge base.

Returns:

FunctionManager with all functions

Return type:

angr.knowledge_plugins.FunctionManager

make_copy(copy_to)

Copy self attributes to the new object.

Parameters:

copy_to (CFGBase) – The target to copy to.

Returns:

None

copy()

output()

generate_index()

Generate an index of all nodes in the graph in order to speed up get_any_node() with anyaddr=True.

Returns:

None

get_predecessors(**kwargs)

get_successors(**kwargs)

get_successors_and_jumpkind(**kwargs)

get_all_predecessors(**kwargs)

get_all_successors(**kwargs)

get_node(**kwargs)

get_any_node(**kwargs)

get_all_nodes(**kwargs)

nodes(**kwargs)

nodes_iter(**kwargs)

get_loop_back_edges()

get_branching_nodes(**kwargs)

get_exit_stmt_idx(**kwargs)

property graph: DiGraph

remove_edge(block_from, block_to)

is_thumb_addr(addr)

normalize()

Normalize the CFG, making sure that there are no overlapping basic blocks.

Note that this method will not alter transition graphs of each function in self.kb.functions. You may call normalize() on each Function object to normalize their transition graphs.

Returns:

None

mark_function_alignments()

Find all potential function alignments and mark them.

Note that it is not always correct to simply remove them, because these functions may not be actual alignments but part of an actual function, and is incorrectly marked as an individual function because of failures in resolving indirect jumps. An example is in the test binary x86_64/dir_gcc_-O0 0x40541d (indirect jump at 0x4051b0). If the indirect jump cannot be correctly resolved, removing function 0x40541d will cause a missing label failure in reassembler.

Returns:

None

make_functions()

Revisit the entire control flow graph, create Function instances accordingly, and correctly put blocks into each function.

Although Function objects are crated during the CFG recovery, they are neither sound nor accurate. With a pre-constructed CFG, this method rebuilds all functions bearing the following rules:

• A block may only belong to one function.

• Small functions lying inside the startpoint and the endpoint of another function will be merged with the other function

• Tail call optimizations are detected.

• PLT stubs are aligned by 16.

Returns:

None

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

exception angr.analyses.cfg.cfg_fast.ContinueScanningNotification

Bases: RuntimeError

A notification raised by _next_code_addr_core() to indicate no code address is found and _next_code_addr_core() should be invoked again.

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class angr.analyses.cfg.cfg_fast.ARMDecodingMode

Bases: object

Enums indicating decoding mode for ARM code.

ARM = 0

THUMB = 1

class angr.analyses.cfg.cfg_fast.DecodingAssumption(addr, size, mode)

Bases: object

Describes the decoding mode (ARM/THUMB) for a given basic block identified by its address.

Parameters:

• addr (int) –

• size (int) –

• mode (int) –

__init__(addr, size, mode)

Parameters:

• addr (int) –

• size (int) –

• mode (int) –

add_data_seg(addr, size)

Return type:

None

Parameters:

• addr (int) –

• size (int) –

class angr.analyses.cfg.cfg_fast.FunctionReturn(callee_func_addr, caller_func_addr, call_site_addr, return_to)

Bases: object

FunctionReturn describes a function call in a specific location and its return location. Hashable and equatable

__init__(callee_func_addr, caller_func_addr, call_site_addr, return_to)

callee_func_addr

caller_func_addr

call_site_addr

return_to

class angr.analyses.cfg.cfg_fast.PendingJobs(functions, deregister_job_callback)

Bases: object

A collection of pending jobs during CFG recovery.

__init__(functions, deregister_job_callback)

add_job(job)

pop_job(returning=True)

Pop a job from the pending jobs list.

When returning == True, we prioritize the jobs whose functions are known to be returning (function.returning is True). As an optimization, we are sorting the pending jobs list according to job.function.returning.

Parameters:

returning (bool) – Only pop a pending job if the corresponding function returns.

Returns:

A pending job if we can find one, or None if we cannot find any that satisfies the requirement.

Return type:

angr.analyses.cfg.cfg_fast.CFGJob

cleanup()

Remove those pending exits if: a) they are the return exits of non-returning SimProcedures b) they are the return exits of non-returning syscalls b) they are the return exits of non-returning functions

Returns:

None

add_returning_function(func_addr)

Mark a function as returning.

Parameters:

func_addr (int) – Address of the function that returns.

Returns:

None

add_nonreturning_function(func_addr)

Mark a function as not returning.

Parameters:

func_addr (int) – Address of the function that does not return.

Returns:

None

clear_updated_functions()

Clear the updated_functions set.

Returns:

None

class angr.analyses.cfg.cfg_fast.FunctionEdge

Bases: object

Describes an edge in functions’ transition graphs. Base class for all types of edges.

apply(cfg)

src_func_addr

stmt_idx

ins_addr

class angr.analyses.cfg.cfg_fast.FunctionTransitionEdge(src_node, dst_addr, src_func_addr, to_outside=False, dst_func_addr=None, stmt_idx=None, ins_addr=None, is_exception=False)

Bases: FunctionEdge

Describes a transition edge in functions’ transition graphs.

__init__(src_node, dst_addr, src_func_addr, to_outside=False, dst_func_addr=None, stmt_idx=None, ins_addr=None, is_exception=False)

src_node

dst_addr

src_func_addr

to_outside

dst_func_addr

stmt_idx

ins_addr

is_exception

apply(cfg)

class angr.analyses.cfg.cfg_fast.FunctionCallEdge(src_node, dst_addr, ret_addr, src_func_addr, syscall=False, stmt_idx=None, ins_addr=None)

Bases: FunctionEdge

Describes a call edge in functions’ transition graphs.

__init__(src_node, dst_addr, ret_addr, src_func_addr, syscall=False, stmt_idx=None, ins_addr=None)

src_node

dst_addr

ret_addr

src_func_addr

syscall

stmt_idx

ins_addr

apply(cfg)

class angr.analyses.cfg.cfg_fast.FunctionFakeRetEdge(src_node, dst_addr, src_func_addr, confirmed=None)

Bases: FunctionEdge

Describes a FakeReturn (also called fall-through) edge in functions’ transition graphs.

__init__(src_node, dst_addr, src_func_addr, confirmed=None)

src_node

dst_addr

src_func_addr

confirmed

apply(cfg)

ins_addr

stmt_idx

class angr.analyses.cfg.cfg_fast.FunctionReturnEdge(ret_from_addr, ret_to_addr, dst_func_addr)

Bases: FunctionEdge

Describes a return (from a function call or a syscall) edge in functions’ transition graphs.

__init__(ret_from_addr, ret_to_addr, dst_func_addr)

ret_from_addr

ret_to_addr

dst_func_addr

apply(cfg)

ins_addr

src_func_addr

stmt_idx

class angr.analyses.cfg.cfg_fast.CFGJobType(value)

Bases: Enum

Defines the type of work of a CFGJob

NORMAL = 0

FUNCTION_PROLOGUE = 1

COMPLETE_SCANNING = 2

IFUNC_HINTS = 3

DATAREF_HINTS = 4

class angr.analyses.cfg.cfg_fast.CFGJob(addr, func_addr, jumpkind, ret_target=None, last_addr=None, src_node=None, src_ins_addr=None, src_stmt_idx=None, returning_source=None, syscall=False, func_edges=None, job_type=CFGJobType.NORMAL, gp=None)

Bases: object

Defines a job to work on during the CFG recovery

Parameters:

• addr (int) –

• func_addr (int) –

• jumpkind (str) –

• ret_target (int | None) –

• last_addr (int | None) –

• src_node (CFGNode | None) –

• src_ins_addr (int | None) –

• src_stmt_idx (int | None) –

• syscall (bool) –

• func_edges (List | None) –

• job_type (CFGJobType) –

• gp (int | None) –

__init__(addr, func_addr, jumpkind, ret_target=None, last_addr=None, src_node=None, src_ins_addr=None, src_stmt_idx=None, returning_source=None, syscall=False, func_edges=None, job_type=CFGJobType.NORMAL, gp=None)

Parameters:

• addr (int) –

• func_addr (int) –

• jumpkind (str) –

• ret_target (int | None) –

• last_addr (int | None) –

• src_node (CFGNode | None) –

• src_ins_addr (int | None) –

• src_stmt_idx (int | None) –

• syscall (bool) –

• func_edges (List | None) –

• job_type (CFGJobType) –

• gp (int | None) –

addr

func_addr

jumpkind

ret_target

last_addr

src_node

src_ins_addr

src_stmt_idx

returning_source

syscall

job_type

gp

add_function_edge(edge)

apply_function_edges(cfg, clear=False)

class angr.analyses.cfg.cfg_fast.CFGFast(binary=None, objects=None, regions=None, pickle_intermediate_results=False, symbols=True, function_prologues=True, resolve_indirect_jumps=True, force_segment=False, force_smart_scan=True, force_complete_scan=False, indirect_jump_target_limit=100000, data_references=True, cross_references=False, normalize=False, start_at_entry=True, function_starts=None, extra_memory_regions=None, data_type_guessing_handlers=None, arch_options=None, indirect_jump_resolvers=None, base_state=None, exclude_sparse_regions=True, skip_specific_regions=True, heuristic_plt_resolving=None, detect_tail_calls=False, low_priority=False, cfb=None, model=None, use_patches=False, elf_eh_frame=True, exceptions=True, skip_unmapped_addrs=True, nodecode_window_size=512, nodecode_threshold=0.3, nodecode_step=16483, indirect_calls_always_return=None, jumptable_resolver_resolves_calls=None, start=None, end=None, collect_data_references=None, extra_cross_references=None, **extra_arch_options)

Bases: ForwardAnalysis, CFGBase

We find functions inside the given binary, and build a control-flow graph in very fast manners: instead of simulating program executions, keeping track of states, and performing expensive data-flow analysis, CFGFast will only perform light-weight analyses combined with some heuristics, and with some strong assumptions.

In order to identify as many functions as possible, and as accurate as possible, the following operation sequence is followed:

# Active scanning

• If the binary has “function symbols” (TODO: this term is not accurate enough), they are starting points of the code scanning

• If the binary does not have any “function symbol”, we will first perform a function prologue scanning on the entire binary, and start from those places that look like function beginnings

• Otherwise, the binary’s entry point will be the starting point for scanning

# Passive scanning

• After all active scans are done, we will go through the whole image and scan all code pieces

Due to the nature of those techniques that are used here, a base address is often not required to use this analysis routine. However, with a correct base address, CFG recovery will almost always yield a much better result. A custom analysis, called GirlScout, is specifically made to recover the base address of a binary blob. After the base address is determined, you may want to reload the binary with the new base address by creating a new Project object, and then re-recover the CFG.

PRINTABLES = b'0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~ \t\n\r'

SPECIAL_THUNKS = {'AMD64': {b'\xe8\x07\x00\x00\x00\xf3\x90\x0f\xae\xe8\xeb\xf9H\x89\x04$\xc3': ('jmp', 'rax'), b'\xe8\x07\x00\x00\x00\xf3\x90\x0f\xae\xe8\xeb\xf9H\x8dd$\x08\xc3': ('ret',)}}

tag: Optional[str] = 'CFGFast'

__init__(binary=None, objects=None, regions=None, pickle_intermediate_results=False, symbols=True, function_prologues=True, resolve_indirect_jumps=True, force_segment=False, force_smart_scan=True, force_complete_scan=False, indirect_jump_target_limit=100000, data_references=True, cross_references=False, normalize=False, start_at_entry=True, function_starts=None, extra_memory_regions=None, data_type_guessing_handlers=None, arch_options=None, indirect_jump_resolvers=None, base_state=None, exclude_sparse_regions=True, skip_specific_regions=True, heuristic_plt_resolving=None, detect_tail_calls=False, low_priority=False, cfb=None, model=None, use_patches=False, elf_eh_frame=True, exceptions=True, skip_unmapped_addrs=True, nodecode_window_size=512, nodecode_threshold=0.3, nodecode_step=16483, indirect_calls_always_return=None, jumptable_resolver_resolves_calls=None, start=None, end=None, collect_data_references=None, extra_cross_references=None, **extra_arch_options)

Parameters:

• binary – The binary to recover CFG on. By default the main binary is used.

• objects – A list of objects to recover the CFG on. By default it will recover the CFG of all loaded objects.

• regions (iterable) – A list of tuples in the form of (start address, end address) describing memory regions that the CFG should cover.

• pickle_intermediate_results (bool) – If we want to store the intermediate results or not.

• symbols (bool) – Get function beginnings from symbols in the binary.

• function_prologues (bool) – Scan the binary for function prologues, and use those positions as function beginnings

• resolve_indirect_jumps (bool) – Try to resolve indirect jumps. This is necessary to resolve jump targets from jump tables, etc.

• force_segment (bool) – Force CFGFast to rely on binary segments instead of sections.

• force_complete_scan (bool) – Perform a complete scan on the binary and maximize the number of identified code blocks.

• data_references (bool) – Enables the collection of references to data used by individual instructions. This does not collect ‘cross-references’, particularly those that involve multiple instructions. For that, see cross_references

• cross_references (bool) – Whether CFGFast should collect “cross-references” from the entire program or not. This will populate the knowledge base with references to and from each recognizable address constant found in the code. Note that, because this performs constant propagation on the entire program, it may be much slower and consume more memory. This option implies data_references=True.

• normalize (bool) – Normalize the CFG as well as all function graphs after CFG recovery.

• start_at_entry (bool) – Begin CFG recovery at the entry point of this project. Setting it to False prevents CFGFast from viewing the entry point as one of the starting points of code scanning.

• function_starts (list) – A list of extra function starting points. CFGFast will try to resume scanning from each address in the list.

• extra_memory_regions (list) – A list of 2-tuple (start-address, end-address) that shows extra memory regions. Integers falling inside will be considered as pointers.

• indirect_jump_resolvers (list) – A custom list of indirect jump resolvers. If this list is None or empty, default indirect jump resolvers specific to this architecture and binary types will be loaded.

• base_state – A state to use as a backer for all memory loads

• detect_tail_calls (bool) – Enable aggressive tail-call optimization detection.

• elf_eh_frame (bool) – Retrieve function starts (and maybe sizes later) from the .eh_frame of ELF binaries.

• skip_unmapped_addrs – Ignore all branches into unmapped regions. True by default. You may want to set it to False if you are analyzing manually patched binaries or malware samples.

• indirect_calls_always_return (Optional[bool]) – Should CFG assume indirect calls must return or not. Assuming indirect calls must return will significantly reduce the number of constant propagation runs, but may reduce the overall CFG recovery precision when facing non-returning indirect calls. By default, we only assume indirect calls always return for large binaries (region > 50KB).

• jumptable_resolver_resolves_calls (Optional[bool]) – Whether JumpTableResolver should resolve indirect calls or not. Most indirect calls in C++ binaries or UEFI binaries cannot be resolved using jump table resolver and must be resolved using their specific resolvers. By default, we will only disable JumpTableResolver from resolving indirect calls for large binaries (region > 50 KB).

• start (int) – (Deprecated) The beginning address of CFG recovery.

• end (int) – (Deprecated) The end address of CFG recovery.

• arch_options (CFGArchOptions) – Architecture-specific options.

• extra_arch_options (dict) – Any key-value pair in kwargs will be seen as an arch-specific option and will be used to set the option value in self._arch_options.

Extra parameters that angr.Analysis takes:

Parameters:

• progress_callback – Specify a callback function to get the progress during CFG recovery.

• show_progressbar (bool) – Should CFGFast show a progressbar during CFG recovery or not.

• indirect_calls_always_return (bool | None) –

• jumptable_resolver_resolves_calls (bool | None) –

Returns:

None

property graph

property memory_data

property jump_tables

property insn_addr_to_memory_data

do_full_xrefs(overlay_state=None)

Perform xref recovery on all functions.

Parameters:

overlay (SimState) – An overlay state for loading constant data.

Returns:

None

abort()

Abort the analysis :return: None

property context_sensitivity_level

copy()

downsize()

errors = []

property functions

A reference to the FunctionManager in the current knowledge base.

Returns:

FunctionManager with all functions

Return type:

angr.knowledge_plugins.FunctionManager

generate_index()

Generate an index of all nodes in the graph in order to speed up get_any_node() with anyaddr=True.

Returns:

None

get_all_nodes(**kwargs)

get_all_predecessors(**kwargs)

get_all_successors(**kwargs)

get_any_node(**kwargs)

get_branching_nodes(**kwargs)

get_exit_stmt_idx(**kwargs)

get_loop_back_edges()

get_node(**kwargs)

get_predecessors(**kwargs)

get_successors(**kwargs)

get_successors_and_jumpkind(**kwargs)

has_job(job)

Checks whether there exists another job which has the same job key. :type job: TypeVar(JobType) :param job: The job to check.

Return type:

bool

Returns:

True if there exists another job with the same key, False otherwise.

Parameters:

job (JobType) –

is_thumb_addr(addr)

property jobs

make_copy(copy_to)

Copy self attributes to the new object.

Parameters:

copy_to (CFGBase) – The target to copy to.

Returns:

None

make_functions()

Revisit the entire control flow graph, create Function instances accordingly, and correctly put blocks into each function.

Although Function objects are crated during the CFG recovery, they are neither sound nor accurate. With a pre-constructed CFG, this method rebuilds all functions bearing the following rules:

• A block may only belong to one function.

• Small functions lying inside the startpoint and the endpoint of another function will be merged with the other function

• Tail call optimizations are detected.

• PLT stubs are aligned by 16.

Returns:

None

mark_function_alignments()

Find all potential function alignments and mark them.

Note that it is not always correct to simply remove them, because these functions may not be actual alignments but part of an actual function, and is incorrectly marked as an individual function because of failures in resolving indirect jumps. An example is in the test binary x86_64/dir_gcc_-O0 0x40541d (indirect jump at 0x4051b0). If the indirect jump cannot be correctly resolved, removing function 0x40541d will cause a missing label failure in reassembler.

Returns:

None

property model: CFGModel

Get the CFGModel instance. :return: The CFGModel instance that this analysis currently uses.

named_errors = {}

nodes(**kwargs)

nodes_iter(**kwargs)

normalize()

Normalize the CFG, making sure that there are no overlapping basic blocks.

Note that this method will not alter transition graphs of each function in self.kb.functions. You may call normalize() on each Function object to normalize their transition graphs.

Returns:

None

property normalized

remove_edge(block_from, block_to)

property should_abort

Should the analysis be terminated. :return: True/False

indirect_jumps: Dict[int, IndirectJump]

project: Project

kb: KnowledgeBase

output()

generate_code_cover(**kwargs)

class angr.analyses.cfg.cfg_arch_options.CFGArchOptions(arch, **options)

Bases: object

Stores architecture-specific options and settings, as well as the detailed explanation of those options and settings.

Suppose ao is the CFGArchOptions object, and there is an option called ret_jumpkind_heuristics, you can access it by ao.ret_jumpkind_heuristics and set its value via ao.ret_jumpkind_heuristics = True

Variables:

• OPTIONS (dict) – A dict of all default options for different architectures.

• arch (archinfo.Arch) – The architecture object.

• _options (dict) – Values of all CFG options that are specific to the current architecture.

OPTIONS = {'ARMCortexM': {'pattern_match_ifuncs': (<class 'bool'>, True), 'ret_jumpkind_heuristics': (<class 'bool'>, True), 'switch_mode_on_nodecode': (<class 'bool'>, False)}, 'ARMEL': {'pattern_match_ifuncs': (<class 'bool'>, True), 'ret_jumpkind_heuristics': (<class 'bool'>, True), 'switch_mode_on_nodecode': (<class 'bool'>, True)}, 'ARMHF': {'pattern_match_ifuncs': (<class 'bool'>, True), 'ret_jumpkind_heuristics': (<class 'bool'>, True), 'switch_mode_on_nodecode': (<class 'bool'>, True)}}

__init__(arch, **options)

Constructor.

Parameters:

• arch (archinfo.Arch) – The architecture instance.

• options (dict) – Architecture-specific options, which will be used to initialize this object.

arch = None

class angr.analyses.cfg.cfg_job_base.BlockID(addr, callsite_tuples, jump_type)

Bases: object

A context-sensitive key for a SimRun object.

__init__(addr, callsite_tuples, jump_type)

callsite_repr()

static new(addr, callstack_suffix, jumpkind)

property func_addr

class angr.analyses.cfg.cfg_job_base.FunctionKey(addr, callsite_tuples)

Bases: object

A context-sensitive key for a function.

__init__(addr, callsite_tuples)

callsite_repr()

static new(addr, callsite_tuples)

class angr.analyses.cfg.cfg_job_base.CFGJobBase(addr, state, context_sensitivity_level, block_id=None, src_block_id=None, src_exit_stmt_idx=None, src_ins_addr=None, jumpkind=None, call_stack=None, is_narrowing=False, skip=False, final_return_address=None)

Bases: object

Describes an entry in CFG or VFG. Only used internally by the analysis.

Parameters:

• state (SimState) –

• jumpkind (str | None) –

__init__(addr, state, context_sensitivity_level, block_id=None, src_block_id=None, src_exit_stmt_idx=None, src_ins_addr=None, jumpkind=None, call_stack=None, is_narrowing=False, skip=False, final_return_address=None)

Parameters:

• state (SimState) –

• jumpkind (str | None) –

property call_stack

call_stack_copy()

get_call_stack_suffix()

property func_addr

property current_stack_pointer

class angr.analyses.cfg.indirect_jump_resolvers.amd64_elf_got.AMD64ElfGotResolver(project)

Bases: IndirectJumpResolver

A timeless indirect jump resolver that resolves GOT entries on AMD64 ELF binaries.

__init__(project)

filter(cfg, addr, func_addr, block, jumpkind)

Check if this resolution method may be able to resolve the indirect jump or not.

Parameters:

• addr (int) – Basic block address of this indirect jump.

• func_addr (int) – Address of the function that this indirect jump belongs to.

• block – The basic block. The type is determined by the backend being used. It’s pyvex.IRSB if pyvex is used as the backend.

• jumpkind (str) – The jumpkind.

Returns:

True if it is possible for this resolution method to resolve the specific indirect jump, False otherwise.

Return type:

bool

resolve(cfg, addr, func_addr, block, jumpkind, func_graph_complete=True, **kwargs)

Resolve an indirect jump.

Parameters:

• cfg – The CFG analysis object.

• addr (int) – Basic block address of this indirect jump.

• func_addr (int) – Address of the function that this indirect jump belongs to.

• block – The basic block. The type is determined by the backend being used. It’s pyvex.IRSB if pyvex is used as the backend.

• jumpkind (str) – The jumpkind.

• func_graph_complete (bool) – True if the function graph is complete at this point (except for nodes that this indirect jump node dominates).

Returns:

A tuple of a boolean indicating whether the resolution is successful or not, and a list of resolved targets (ints).

Return type:

tuple

class angr.analyses.cfg.indirect_jump_resolvers.arm_elf_fast.ArmElfFastResolver(project)

Bases: IndirectJumpResolver

Resolves the indirect jump in ARM ELF binaries where all internal function calls are performed in the following manner:

ldr r3, [pc+#0x124]  ; load a constant from the constant_pool
blx r3

__init__(project)

filter(cfg, addr, func_addr, block, jumpkind)

Check if this resolution method may be able to resolve the indirect jump or not.

Parameters:

• addr (int) – Basic block address of this indirect jump.

• func_addr (int) – Address of the function that this indirect jump belongs to.

• block – The basic block. The type is determined by the backend being used. It’s pyvex.IRSB if pyvex is used as the backend.

• jumpkind (str) – The jumpkind.

Returns:

True if it is possible for this resolution method to resolve the specific indirect jump, False otherwise.

Return type:

bool

resolve(cfg, addr, func_addr, block, jumpkind, func_graph_complete=True, **kwargs)

The main resolving function.

Parameters:

• cfg – A CFG instance.

• addr (int) – Address of the IRSB.

• func_addr (int) – Address of the function.

• block – The IRSB.

• jumpkind (str) – The jumpkind.

• func_graph_complete (bool) –

Returns:

Return type:

tuple

class angr.analyses.cfg.indirect_jump_resolvers.x86_pe_iat.X86PeIatResolver(project)

Bases: IndirectJumpResolver

A timeless indirect jump resolver for IAT in x86 PEs.

__init__(project)

filter(cfg, addr, func_addr, block, jumpkind)

Check if this resolution method may be able to resolve the indirect jump or not.

Parameters:

• addr (int) – Basic block address of this indirect jump.

• func_addr (int) – Address of the function that this indirect jump belongs to.

• block – The basic block. The type is determined by the backend being used. It’s pyvex.IRSB if pyvex is used as the backend.

• jumpkind (str) – The jumpkind.

Returns:

True if it is possible for this resolution method to resolve the specific indirect jump, False otherwise.

Return type:

bool

resolve(cfg, addr, func_addr, block, jumpkind, func_graph_complete=True, **kwargs)

Resolve an indirect jump.

Parameters:

• cfg – The CFG analysis object.

• addr (int) – Basic block address of this indirect jump.

• func_addr (int) – Address of the function that this indirect jump belongs to.

• block – The basic block. The type is determined by the backend being used. It’s pyvex.IRSB if pyvex is used as the backend.

• jumpkind (str) – The jumpkind.

• func_graph_complete (bool) – True if the function graph is complete at this point (except for nodes that this indirect jump node dominates).

Returns:

A tuple of a boolean indicating whether the resolution is successful or not, and a list of resolved targets (ints).

Return type:

tuple

angr.analyses.cfg.indirect_jump_resolvers.mips_elf_fast.enable_profiling()

angr.analyses.cfg.indirect_jump_resolvers.mips_elf_fast.disable_profiling()

class angr.analyses.cfg.indirect_jump_resolvers.mips_elf_fast.OverwriteTmpValueCallback(gp_value)

Bases: object

Overwrites temporary values during resolution

__init__(gp_value)

overwrite_tmp_value(state)

class angr.analyses.cfg.indirect_jump_resolvers.mips_elf_fast.MipsElfFastResolver(project)

Bases: IndirectJumpResolver

A timeless indirect jump resolver for R9-based indirect function calls in MIPS ELFs.

__init__(project)

filter(cfg, addr, func_addr, block, jumpkind)

Check if this resolution method may be able to resolve the indirect jump or not.

Parameters:

• addr (int) – Basic block address of this indirect jump.

• func_addr (int) – Address of the function that this indirect jump belongs to.

• block – The basic block. The type is determined by the backend being used. It’s pyvex.IRSB if pyvex is used as the backend.

• jumpkind (str) – The jumpkind.

Returns:

True if it is possible for this resolution method to resolve the specific indirect jump, False otherwise.

Return type:

bool

resolve(cfg, addr, func_addr, block, jumpkind, func_graph_complete=True, **kwargs)

Wrapper for _resolve that slowly increments the max_depth used by Blade for finding sources until we can resolve the addr or we reach the default max_depth

Parameters:

• cfg – A CFG instance.

• addr (int) – IRSB address.

• func_addr (int) – The function address.

• block (pyvex.IRSB) – The IRSB.

• jumpkind (str) – The jumpkind.

• func_graph_complete (bool) –

Returns:

If it was resolved and targets alongside it

Return type:

tuple

class angr.analyses.cfg.indirect_jump_resolvers.x86_elf_pic_plt.X86ElfPicPltResolver(project)

Bases: IndirectJumpResolver

In X86 ELF position-independent code, PLT stubs uses ebx to resolve library calls, where ebx stores the address to the beginning of the GOT. We resolve the target by forcing ebx to be the beginning of the GOT and simulate the execution in fast path mode.

__init__(project)

filter(cfg, addr, func_addr, block, jumpkind)

Check if this resolution method may be able to resolve the indirect jump or not.

Parameters:

• addr (int) – Basic block address of this indirect jump.

• func_addr (int) – Address of the function that this indirect jump belongs to.

• block – The basic block. The type is determined by the backend being used. It’s pyvex.IRSB if pyvex is used as the backend.

• jumpkind (str) – The jumpkind.

Returns:

True if it is possible for this resolution method to resolve the specific indirect jump, False otherwise.

Return type:

bool

resolve(cfg, addr, func_addr, block, jumpkind, func_graph_complete=True, **kwargs)

Resolve an indirect jump.

Parameters:

• cfg – The CFG analysis object.

• addr (int) – Basic block address of this indirect jump.

• func_addr (int) – Address of the function that this indirect jump belongs to.

• block – The basic block. The type is determined by the backend being used. It’s pyvex.IRSB if pyvex is used as the backend.

• jumpkind (str) – The jumpkind.

• func_graph_complete (bool) – True if the function graph is complete at this point (except for nodes that this indirect jump node dominates).

Returns:

A tuple of a boolean indicating whether the resolution is successful or not, and a list of resolved targets (ints).

Return type:

tuple

angr.analyses.cfg.indirect_jump_resolvers.default_resolvers.default_indirect_jump_resolvers(obj, project)

exception angr.analyses.cfg.indirect_jump_resolvers.jumptable.NotAJumpTableNotification

Bases: AngrError

Exception raised to indicate this is not (or does not appear to be) a jump table.

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class angr.analyses.cfg.indirect_jump_resolvers.jumptable.UninitReadMeta

Bases: object

Uninitialized read remapping details.

uninit_read_base = 201326592

class angr.analyses.cfg.indirect_jump_resolvers.jumptable.AddressTransferringTypes

Bases: object

Types of address transfer.

Assignment = 0

SignedExtension = 1

UnsignedExtension = 2

Truncation = 3

Or1 = 4

ShiftLeft = 5

ShiftRight = 6

class angr.analyses.cfg.indirect_jump_resolvers.jumptable.JumpTargetBaseAddr(stmt_loc, stmt, tmp, base_addr=None, tmp_1=None)

Bases: object

Model for jump targets and their data origin.

__init__(stmt_loc, stmt, tmp, base_addr=None, tmp_1=None)

property base_addr_available

class angr.analyses.cfg.indirect_jump_resolvers.jumptable.ConstantValueManager(project, kb, func)

Bases: object

Manages the loading of registers who hold constant values.

Parameters:

func (Function) –

__init__(project, kb, func)

Parameters:

func (Function) –

project

kb

func

mapping

reg_read_callback(state)

Parameters:

state (SimState) –

class angr.analyses.cfg.indirect_jump_resolvers.jumptable.JumpTableProcessorState(arch)

Bases: object

The state used in JumpTableProcessor.

__init__(arch)

arch

is_jumptable

stmts_to_instrument

regs_to_initialize

class angr.analyses.cfg.indirect_jump_resolvers.jumptable.RegOffsetAnnotation(reg_offset)

Bases: Annotation

Register Offset annotation.

Parameters:

reg_offset (RegisterOffset) –

__init__(reg_offset)

Parameters:

reg_offset (RegisterOffset) –

reg_offset

property relocatable

Returns whether this annotation can be relocated in a simplification.

Returns:

True if it can be relocated, false otherwise.

property eliminatable

Returns whether this annotation can be eliminated in a simplification.

Returns:

True if eliminatable, False otherwise

relocate(src, dst)

This is called when an annotation has to be relocated because of simplifications.

Consider the following case:

x = claripy.BVS(‘x’, 32) zero = claripy.BVV(0, 32).add_annotation(your_annotation) y = x + zero

Here, one of three things can happen:

1. if your_annotation.eliminatable is True, the simplifiers will simply eliminate your_annotation along with zero and y is x will hold

2. elif your_annotation.relocatable is False, the simplifier will abort and y will never be simplified

3. elif your_annotation.relocatable is True, the simplifier will run, determine that the simplified result of x + zero will be x. It will then call your_annotation.relocate(zero, x) to move the annotation away from the AST that is about to be eliminated.

Parameters:

• src – the old AST that was eliminated in the simplification

• dst – the new AST (the result of a simplification)

Returns:

the annotation that will be applied to dst

class angr.analyses.cfg.indirect_jump_resolvers.jumptable.JumpTableProcessor(project, indirect_jump_node_pred_addrs, bp_sp_diff=256)

Bases: SimEngineLightVEXMixin, SimEngineLight

Implements a simple and stupid data dependency tracking for stack and register variables.

Also determines which statements to instrument during static execution of the slice later. For example, the following example is not uncommon in non-optimized binaries:

    mov  [rbp+var_54], 1
loc_4051a6:
    cmp  [rbp+var_54], 6
    ja   loc_405412 (default)
loc_4051b0:
    mov  eax, [rbp+var_54]
    mov  rax, qword [rax*8+0x223a01]
    jmp  rax

We want to instrument the first instruction and replace the constant 1 with a symbolic variable, otherwise we will not be able to recover all jump targets later in block 0x4051b0.

Parameters:

indirect_jump_node_pred_addrs (Set[int]) –

__init__(project, indirect_jump_node_pred_addrs, bp_sp_diff=256)

Parameters:

indirect_jump_node_pred_addrs (Set[int]) –

static extract_offset_to_sp(spoffset_expr)

Extract the offset to the original stack pointer.

Parameters:

spoffset_expr (Base) – The claripy AST to parse.

Return type:

Optional[int]

Returns:

The offset to the original stack pointer, or None if spoffset_expr is not a supported type of SpOffset expression.

process(state, *args, **kwargs)

The main entry point for an engine. Should take a state and return a result.

Parameters:

state – The state to proceed from

Returns:

The result. Whatever you want ;)

static sp_offset(bits, offset)

Parameters:

• bits (int) –

• offset (int) –

class angr.analyses.cfg.indirect_jump_resolvers.jumptable.StoreHook

Bases: object

Hook for memory stores.

static hook(state)

class angr.analyses.cfg.indirect_jump_resolvers.jumptable.LoadHook

Bases: object

Hook for memory loads.

__init__()

hook_before(state)

hook_after(state)

class angr.analyses.cfg.indirect_jump_resolvers.jumptable.PutHook

Bases: object

Hook for register writes.

static hook(state)

class angr.analyses.cfg.indirect_jump_resolvers.jumptable.RegisterInitializerHook(reg_offset, reg_bits, value)

Bases: object

Hook for register init.

__init__(reg_offset, reg_bits, value)

hook(state)

class angr.analyses.cfg.indirect_jump_resolvers.jumptable.BSSHook(project, bss_regions)

Bases: object

Hook for BSS read/write.

__init__(project, bss_regions)

bss_memory_read_hook(state)

bss_memory_write_hook(state)

class angr.analyses.cfg.indirect_jump_resolvers.jumptable.MIPSGPHook(gp_offset, gp)

Bases: object

Hooks all reads from and writes into the gp register for MIPS32 binaries.

Parameters:

• gp_offset (int) –

• gp (int) –

__init__(gp_offset, gp)

Parameters:

• gp_offset (int) –

• gp (int) –

gp_register_read_hook(state)

gp_register_write_hook(state)

class angr.analyses.cfg.indirect_jump_resolvers.jumptable.JumpTableResolver(project, resolve_calls=True)

Bases: IndirectJumpResolver

A generic jump table resolver.

This is a fast jump table resolution. For performance concerns, we made the following assumptions:

• The final jump target comes from the memory.

• The final jump target must be directly read out of the memory, without any further modification or altering.

Progressively larger program slices will be analyzed to determine jump table location and size. If the size of the table cannot be determined, a guess will be made based on how many entries in the table appear valid.

Parameters:

resolve_calls (bool) –

__init__(project, resolve_calls=True)

Parameters:

resolve_calls (bool) –

filter(cfg, addr, func_addr, block, jumpkind)

Check if this resolution method may be able to resolve the indirect jump or not.

Parameters:

• addr (int) – Basic block address of this indirect jump.

• func_addr (int) – Address of the function that this indirect jump belongs to.

• block – The basic block. The type is determined by the backend being used. It’s pyvex.IRSB if pyvex is used as the backend.

• jumpkind (str) – The jumpkind.

Returns:

True if it is possible for this resolution method to resolve the specific indirect jump, False otherwise.

Return type:

bool

resolve(cfg, addr, func_addr, block, jumpkind, func_graph_complete=True, **kwargs)

Resolves jump tables.

Parameters:

• cfg – A CFG instance.

• addr (int) – IRSB address.

• func_addr (int) – The function address.

• block (pyvex.IRSB) – The IRSB.

• func_graph_complete (bool) –

Returns:

A bool indicating whether the indirect jump is resolved successfully, and a list of resolved targets

Return type:

tuple

angr.analyses.cfg.indirect_jump_resolvers.const_resolver.exists_in_replacements(replacements, block_loc, tmp_var)

class angr.analyses.cfg.indirect_jump_resolvers.const_resolver.ConstantResolver(project)

Bases: IndirectJumpResolver

Resolve an indirect jump by running a constant propagation on the entire function and check if the indirect jump can be resolved to a constant value. This resolver must be run after all other more specific resolvers.

__init__(project)

filter(cfg, addr, func_addr, block, jumpkind)

Check if this resolution method may be able to resolve the indirect jump or not.

Parameters:

• addr (int) – Basic block address of this indirect jump.

• func_addr (int) – Address of the function that this indirect jump belongs to.

• block – The basic block. The type is determined by the backend being used. It’s pyvex.IRSB if pyvex is used as the backend.

• jumpkind (str) – The jumpkind.

Returns:

True if it is possible for this resolution method to resolve the specific indirect jump, False otherwise.

Return type:

bool

resolve(cfg, addr, func_addr, block, jumpkind, func_graph_complete=True, **kwargs)

This function does the actual resolve. Our process is easy: Propagate all values inside the function specified, then extract the tmp_var used for the indirect jump from the basic block. Use the tmp var to locate the constant value stored in the replacements. If not present, returns False tuple.

Parameters:

• cfg – CFG with specified function

• addr (int) – Address of indirect jump

• func_addr (int) – Address of function of indirect jump

• block (Block) – Block of indirect jump (Block object)

• jumpkind (str) – VEX jumpkind (Ijk_Boring or Ijk_Call)

• func_graph_complete (bool) –

Returns:

Bool tuple with replacement address

class angr.analyses.cfg.indirect_jump_resolvers.resolver.IndirectJumpResolver(project, timeless=False, base_state=None)

Bases: object

__init__(project, timeless=False, base_state=None)

filter(cfg, addr, func_addr, block, jumpkind)

Check if this resolution method may be able to resolve the indirect jump or not.

Parameters:

• addr (int) – Basic block address of this indirect jump.

• func_addr (int) – Address of the function that this indirect jump belongs to.

• block – The basic block. The type is determined by the backend being used. It’s pyvex.IRSB if pyvex is used as the backend.

• jumpkind (str) – The jumpkind.

Returns:

True if it is possible for this resolution method to resolve the specific indirect jump, False otherwise.

Return type:

bool

resolve(cfg, addr, func_addr, block, jumpkind, func_graph_complete=True, **kwargs)

Resolve an indirect jump.

Parameters:

• cfg – The CFG analysis object.

• addr (int) – Basic block address of this indirect jump.

• func_addr (int) – Address of the function that this indirect jump belongs to.

• block – The basic block. The type is determined by the backend being used. It’s pyvex.IRSB if pyvex is used as the backend.

• jumpkind (str) – The jumpkind.

• func_graph_complete (bool) – True if the function graph is complete at this point (except for nodes that this indirect jump node dominates).

Returns:

A tuple of a boolean indicating whether the resolution is successful or not, and a list of resolved targets (ints).

Return type:

tuple

class angr.analyses.cfg.cfg_fast_soot.CFGFastSoot(support_jni=False, **kwargs)

Bases: CFGFast

__init__(support_jni=False, **kwargs)

Parameters:

• binary – The binary to recover CFG on. By default the main binary is used.

• objects – A list of objects to recover the CFG on. By default it will recover the CFG of all loaded objects.

• regions (iterable) – A list of tuples in the form of (start address, end address) describing memory regions that the CFG should cover.

• pickle_intermediate_results (bool) – If we want to store the intermediate results or not.

• symbols (bool) – Get function beginnings from symbols in the binary.

• function_prologues (bool) – Scan the binary for function prologues, and use those positions as function beginnings

• resolve_indirect_jumps (bool) – Try to resolve indirect jumps. This is necessary to resolve jump targets from jump tables, etc.

• force_segment (bool) – Force CFGFast to rely on binary segments instead of sections.

• force_complete_scan (bool) – Perform a complete scan on the binary and maximize the number of identified code blocks.

• data_references (bool) – Enables the collection of references to data used by individual instructions. This does not collect ‘cross-references’, particularly those that involve multiple instructions. For that, see cross_references

• cross_references (bool) – Whether CFGFast should collect “cross-references” from the entire program or not. This will populate the knowledge base with references to and from each recognizable address constant found in the code. Note that, because this performs constant propagation on the entire program, it may be much slower and consume more memory. This option implies data_references=True.

• normalize (bool) – Normalize the CFG as well as all function graphs after CFG recovery.

• start_at_entry (bool) – Begin CFG recovery at the entry point of this project. Setting it to False prevents CFGFast from viewing the entry point as one of the starting points of code scanning.

• function_starts (list) – A list of extra function starting points. CFGFast will try to resume scanning from each address in the list.

• extra_memory_regions (list) – A list of 2-tuple (start-address, end-address) that shows extra memory regions. Integers falling inside will be considered as pointers.

• indirect_jump_resolvers (list) – A custom list of indirect jump resolvers. If this list is None or empty, default indirect jump resolvers specific to this architecture and binary types will be loaded.

• base_state – A state to use as a backer for all memory loads

• detect_tail_calls (bool) – Enable aggressive tail-call optimization detection.

• elf_eh_frame (bool) – Retrieve function starts (and maybe sizes later) from the .eh_frame of ELF binaries.

• skip_unmapped_addrs – Ignore all branches into unmapped regions. True by default. You may want to set it to False if you are analyzing manually patched binaries or malware samples.

• indirect_calls_always_return – Should CFG assume indirect calls must return or not. Assuming indirect calls must return will significantly reduce the number of constant propagation runs, but may reduce the overall CFG recovery precision when facing non-returning indirect calls. By default, we only assume indirect calls always return for large binaries (region > 50KB).

• jumptable_resolver_resolves_calls – Whether JumpTableResolver should resolve indirect calls or not. Most indirect calls in C++ binaries or UEFI binaries cannot be resolved using jump table resolver and must be resolved using their specific resolvers. By default, we will only disable JumpTableResolver from resolving indirect calls for large binaries (region > 50 KB).

• start (int) – (Deprecated) The beginning address of CFG recovery.

• end (int) – (Deprecated) The end address of CFG recovery.

• arch_options (CFGArchOptions) – Architecture-specific options.

• extra_arch_options (dict) – Any key-value pair in kwargs will be seen as an arch-specific option and will be used to set the option value in self._arch_options.

Extra parameters that angr.Analysis takes:

Parameters:

• progress_callback – Specify a callback function to get the progress during CFG recovery.

• show_progressbar (bool) – Should CFGFast show a progressbar during CFG recovery or not.

Returns:

None

normalize()

Normalize the CFG, making sure that there are no overlapping basic blocks.

Note that this method will not alter transition graphs of each function in self.kb.functions. You may call normalize() on each Function object to normalize their transition graphs.

Returns:

None

make_functions()

Revisit the entire control flow graph, create Function instances accordingly, and correctly put blocks into each function.

Although Function objects are crated during the CFG recovery, they are neither sound nor accurate. With a pre-constructed CFG, this method rebuilds all functions bearing the following rules:

• A block may only belong to one function.

• Small functions lying inside the startpoint and the endpoint of another function will be merged with the other function

• Tail call optimizations are detected.

• PLT stubs are aligned by 16.

Returns:

None

PRINTABLES = b'0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~ \t\n\r'

SPECIAL_THUNKS = {'AMD64': {b'\xe8\x07\x00\x00\x00\xf3\x90\x0f\xae\xe8\xeb\xf9H\x89\x04$\xc3': ('jmp', 'rax'), b'\xe8\x07\x00\x00\x00\xf3\x90\x0f\xae\xe8\xeb\xf9H\x8dd$\x08\xc3': ('ret',)}}

abort()

Abort the analysis :return: None

property context_sensitivity_level

copy()

do_full_xrefs(overlay_state=None)

Perform xref recovery on all functions.

Parameters:

overlay (SimState) – An overlay state for loading constant data.

Returns:

None

downsize()

errors = []

property functions

A reference to the FunctionManager in the current knowledge base.

Returns:

FunctionManager with all functions

Return type:

angr.knowledge_plugins.FunctionManager

generate_code_cover(**kwargs)

generate_index()

Generate an index of all nodes in the graph in order to speed up get_any_node() with anyaddr=True.

Returns:

None

get_all_nodes(**kwargs)

get_all_predecessors(**kwargs)

get_all_successors(**kwargs)

get_any_node(**kwargs)

get_branching_nodes(**kwargs)

get_exit_stmt_idx(**kwargs)

get_loop_back_edges()

get_node(**kwargs)

get_predecessors(**kwargs)

get_successors(**kwargs)

get_successors_and_jumpkind(**kwargs)

property graph

has_job(job)

Checks whether there exists another job which has the same job key. :type job: TypeVar(JobType) :param job: The job to check.

Return type:

bool

Returns:

True if there exists another job with the same key, False otherwise.

Parameters:

job (JobType) –

property insn_addr_to_memory_data

is_thumb_addr(addr)

property jobs

property jump_tables

make_copy(copy_to)

Copy self attributes to the new object.

Parameters:

copy_to (CFGBase) – The target to copy to.

Returns:

None

mark_function_alignments()

Find all potential function alignments and mark them.

Note that it is not always correct to simply remove them, because these functions may not be actual alignments but part of an actual function, and is incorrectly marked as an individual function because of failures in resolving indirect jumps. An example is in the test binary x86_64/dir_gcc_-O0 0x40541d (indirect jump at 0x4051b0). If the indirect jump cannot be correctly resolved, removing function 0x40541d will cause a missing label failure in reassembler.

Returns:

None

property memory_data

property model: CFGModel

Get the CFGModel instance. :return: The CFGModel instance that this analysis currently uses.

named_errors = {}

nodes(**kwargs)

nodes_iter(**kwargs)

property normalized

output()

remove_edge(block_from, block_to)

property should_abort

Should the analysis be terminated. :return: True/False

tag: Optional[str] = 'CFGFast'

indirect_jumps: Dict[int, IndirectJump]

project: Project

kb: KnowledgeBase

class angr.analyses.cfg.segment_list.Segment(start, end, sort)

Bases: object

Representing a memory block. This is not the “Segment” in ELF memory model

__init__(start, end, sort)

Parameters:

• start (int) – Start address.

• end (int) – End address.

• sort (str) – Type of the segment, can be code, data, etc.

Returns:

None

start

end

sort

property size

Calculate the size of the Segment.

Returns:

Size of the Segment.

Return type:

int

copy()

Make a copy of the Segment.

Returns:

A copy of the Segment instance.

Return type:

angr.analyses.cfg_fast.Segment

class angr.analyses.cfg.segment_list.SegmentList

Bases: object

SegmentList describes a series of segmented memory blocks. You may query whether an address belongs to any of the blocks or not, and obtain the exact block(segment) that the address belongs to.

__init__()

search(addr)

Checks which segment that the address addr should belong to, and, returns the offset of that segment. Note that the address may not actually belong to the block.

Parameters:

addr (int) – The address to search

Return type:

int

Returns:

The offset of the segment.

next_free_pos(address)

Returns the next free position with respect to an address, including that address itself

Parameters:

address – The address to begin the search with (including itself)

Returns:

The next free position

next_pos_with_sort_not_in(address, sorts, max_distance=None)

Returns the address of the next occupied block whose sort is not one of the specified ones.

Parameters:

• address (int) – The address to begin the search with (including itself).

• sorts – A collection of sort strings.

• max_distance – The maximum distance between address and the next position. Search will stop after we come across an occupied position that is beyond address + max_distance. This check will be disabled if max_distance is set to None.

Returns:

The next occupied position whose sort is not one of the specified ones, or None if no such position exists.

Return type:

int or None

is_occupied(address)

Check if an address belongs to any segment

Parameters:

address – The address to check

Returns:

True if this address belongs to a segment, False otherwise

occupied_by_sort(address)

Check if an address belongs to any segment, and if yes, returns the sort of the segment

Parameters:

address (int) – The address to check

Return type:

Optional[str]

Returns:

Sort of the segment that occupies this address

occupied_by(address)

Check if an address belongs to any segment, and if yes, returns the beginning, the size, and the sort of the segment.

Parameters:

address (int) – The address to check

Return type:

Optional[Tuple[int, int, str]]

occupy(address, size, sort)

Include a block, specified by (address, size), in this segment list.

Parameters:

• address (int) – The starting address of the block.

• size (int) – Size of the block.

• sort (str) – Type of the block.

Returns:

None

release(address, size)

Remove a block, specified by (address, size), in this segment list.

Parameters:

• address (int) – The starting address of the block.

• size (int) – Size of the block.

Return type:

None

copy()

Make a copy of the SegmentList.

Returns:

A copy of the SegmentList instance.

Return type:

angr.analyses.cfg_fast.SegmentList

property occupied_size

The sum of sizes of all blocks

Returns:

An integer

property has_blocks

Returns if this segment list has any block or not. !is_empty

Returns:

True if it’s not empty, False otherwise

class angr.analyses.cdg.CDG(cfg, start=None, no_construct=False)

Bases: Analysis

Implements a control dependence graph.

__init__(cfg, start=None, no_construct=False)

Constructor.

Parameters:

• cfg – The control flow graph upon which this control dependence graph will build

• start – The starting point to begin constructing the control dependence graph

• no_construct – Skip the construction step. Only used in unit-testing.

property graph

get_post_dominators()

Return the post-dom tree

get_dependants(run)

Return a list of nodes that are control dependent on the given node in the control dependence graph

get_guardians(run)

Return a list of nodes on whom the specific node is control dependent in the control dependence graph

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

exception angr.analyses.datagraph_meta.DataGraphError

Bases: Exception

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class angr.analyses.datagraph_meta.DataGraphMeta

Bases: object

__init__()

get_irsb_at(addr)

pp(imarks=False)

Pretty print the graph. @imarks determine whether the printed graph represents instructions (coarse grained) for easier navigation, or exact statements.

class angr.analyses.code_tagging.CodeTags

Bases: object

HAS_XOR = 'HAS_XOR'

HAS_BITSHIFTS = 'HAS_BITSHIFTS'

HAS_SQL = 'HAS_SQL'

LARGE_SWITCH = 'LARGE_SWITCH'

class angr.analyses.code_tagging.CodeTagging(func)

Bases: Analysis

__init__(func)

analyze()

has_xor()

Detects if there is any xor operation in the function.

Returns:

Tags

has_bitshifts()

Detects if there is any bitwise operation in the function.

Returns:

Tags.

has_sql()

Detects if there is any reference to strings that look like SQL queries.

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

class angr.angrdb.db.AngrDB(project=None)

Bases: object

AngrDB provides a storage solution for an angr project, its knowledge bases, and some other types of data. It is designed to use an SQL-based database as the storage backend.

ALL_TABLES = ['objects']

VERSION = 1

__init__(project=None)

static open_db(db_str='sqlite:///:memory:')

static session_scope(Session)

static save_info(session, key, value)

Save an information entry to the database.

Parameters:

• session –

• key –

• value –

Returns:

static get_info(session, key)

Get an information entry from the database.

Parameters:

• session –

• key –

Returns:

update_dbinfo(session, extra_info=None)

Update the information in database.

Parameters:

• session –

• extra_info (Dict[str, str] | None) –

Returns:

get_dbinfo(session, extra_info=None)

Get database information.

Parameters:

• session –

• extra_info (Dict[str, str] | None) –

Returns:

A dict of information entries.

db_compatible(version)

Checks if the given database version is compatible with the current AngrDB class.

Parameters:

version (int) – The version of the database.

Returns:

True if compatible, False otherwise.

Return type:

bool

dump(db_path, kbs=None, extra_info=None)

Parameters:

• kbs (List[KnowledgeBase] | None) –

• extra_info (Dict[str, Any] | None) –

load(db_path, kb_names=None, other_kbs=None, extra_info=None)

Parameters:

• db_path (str) –

• kb_names (List[str] | None) –

• other_kbs (Dict[str, KnowledgeBase] | None) –

• extra_info (Dict[str, Any] | None) –

class angr.angrdb.models.DbInformation(**kwargs)

Bases: Base

Stores information related to the current database. Basically a key-value store.

id

key

value

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

metadata: MetaData = MetaData()

registry: RegistryType = <sqlalchemy.orm.decl_api.registry object>

class angr.angrdb.models.DbObject(**kwargs)

Bases: Base

Models a binary object.

id

main_object

path

content

backend

backend_args

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

metadata: MetaData = MetaData()

registry: RegistryType = <sqlalchemy.orm.decl_api.registry object>

class angr.angrdb.models.DbKnowledgeBase(**kwargs)

Bases: Base

Models a knowledge base.

id

name

cfgs

funcs

xrefs

comments

labels

var_collections

structured_code

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

metadata: MetaData = MetaData()

registry: RegistryType = <sqlalchemy.orm.decl_api.registry object>

class angr.angrdb.models.DbCFGModel(**kwargs)

Bases: Base

Models a CFGFast instance.

id

kb_id

kb

ident

blob

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

metadata: MetaData = MetaData()

registry: RegistryType = <sqlalchemy.orm.decl_api.registry object>

class angr.angrdb.models.DbFunction(**kwargs)

Bases: Base

Models a Function instance.

id

kb_id

kb

addr

blob

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

metadata: MetaData = MetaData()

registry: RegistryType = <sqlalchemy.orm.decl_api.registry object>

class angr.angrdb.models.DbVariableCollection(**kwargs)

Bases: Base

Models a VariableManagerInternal instance.

id

kb_id

kb

func_addr

ident

blob

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

metadata: MetaData = MetaData()

registry: RegistryType = <sqlalchemy.orm.decl_api.registry object>

class angr.angrdb.models.DbStructuredCode(**kwargs)

Bases: Base

Models a StructuredCode instance.

id

kb_id

kb

func_addr

flavor

expr_comments

stmt_comments

configuration

const_formats

ite_exprs

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

metadata: MetaData = MetaData()

registry: RegistryType = <sqlalchemy.orm.decl_api.registry object>

class angr.angrdb.models.DbXRefs(**kwargs)

Bases: Base

Models an XRefManager instance.

id

kb_id

kb

blob

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

metadata: MetaData = MetaData()

registry: RegistryType = <sqlalchemy.orm.decl_api.registry object>

class angr.angrdb.models.DbComment(**kwargs)

Bases: Base

Models a comment.

id

kb_id

kb

addr

comment

type

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

metadata: MetaData = MetaData()

registry: RegistryType = <sqlalchemy.orm.decl_api.registry object>

class angr.angrdb.models.DbLabel(**kwargs)

Bases: Base

Models a label.

id

kb_id

kb

addr

name

__init__(**kwargs)

A simple constructor that allows initialization from kwargs.

Sets attributes on the constructed instance using the names and values in kwargs.

Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

metadata: MetaData = MetaData()

registry: RegistryType = <sqlalchemy.orm.decl_api.registry object>

class angr.angrdb.serializers.cfg_model.CFGModelSerializer

Bases: object

Serialize/unserialize a CFGModel.

static dump(session, db_kb, ident, cfg_model)

Parameters:

• session –

• db_kb (DbKnowledgeBase) – The database object for KnowledgeBase.

• ident (str) – Identifier of the CFG model.

• cfg_model (CFGModel) – The CFG model to dump.

Returns:

None

static load(session, db_kb, ident, cfg_manager, loader=None)

class angr.angrdb.serializers.comments.CommentsSerializer

Bases: object

Serialize/unserialize comments to/from a database session.

static dump(session, db_kb, comments)

Parameters:

• session –

• db_kb (DbKnowledgeBase) –

• comments (Comments) –

Returns:

None

static load(session, db_kb, kb)

Parameters:

• session –

• db_kb (DbKnowledgeBase) –

• kb (KnowledgeBase) –

Returns:

class angr.angrdb.serializers.funcs.FunctionManagerSerializer

Bases: object

Serialize/unserialize a function manager and its functions.

static dump(session, db_kb, func_manager)

Parameters:

• session –

• db_kb (DbKnowledgeBase) –

• func_manager (FunctionManager) –

Returns:

static load(session, db_kb, kb)

Parameters:

• session –

• db_kb (DbKnowledgeBase) –

• kb (KnowledgeBase) –

Returns:

A loaded function manager.

class angr.angrdb.serializers.kb.KnowledgeBaseSerializer

Bases: object

Serialize/unserialize a KnowledgeBase object.

static dump(session, kb)

Parameters:

• session – The database session object.

• kb (KnowledgeBase) – The KnowledgeBase instance to serialize.

Returns:

None

static load(session, project, name)

Parameters:

session –

Returns:

class angr.angrdb.serializers.labels.LabelsSerializer

Bases: object

Serialize/unserialize labels to/from a database session.

static dump(session, db_kb, labels)

Parameters:

• session –

• db_kb (DbKnowledgeBase) –

• labels (Labels) –

Returns:

None

static load(session, db_kb, kb)

Parameters:

• session –

• db_kb (DbKnowledgeBase) –

• kb (KnowledgeBase) –

Returns:

class angr.angrdb.serializers.loader.LoaderSerializer

Bases: object

Serialize/unserialize a CLE Loader object into/from an angr DB.

backend2name = {<class 'cle.backends.blob.Blob'>: 'blob', <class 'cle.backends.elf.elf.ELF'>: 'elf', <class 'cle.backends.elf.elfcore.ELFCore'>: 'elfcore', <class 'cle.backends.cgc.cgc.CGC'>: 'cgc', <class 'cle.backends.cgc.backedcgc.BackedCGC'>: 'backedcgc', <class 'cle.backends.ihex.Hex'>: 'hex', <class 'cle.backends.java.apk.Apk'>: 'apk', <class 'cle.backends.java.jar.Jar'>: 'jar', <class 'cle.backends.macho.macho.MachO'>: 'mach-o', <class 'cle.backends.minidump.Minidump'>: 'minidump', <class 'cle.backends.named_region.NamedRegion'>: 'named_region', <class 'cle.backends.pe.pe.PE'>: 'pe', <class 'cle.backends.static_archive.StaticArchive'>: 'AR', <class 'cle.backends.te.TE'>: 'te', <class 'cle.backends.uefi_firmware.UefiFirmware'>: 'uefi', <class 'cle.backends.xbe.XBE'>: 'xbe'}

static dump(session, loader)

static load(session)

class angr.angrdb.serializers.xrefs.XRefsSerializer

Bases: object

Serialize/unserialize an XRefs object to/from a database session.

static dump(session, db_kb, xrefs)

Parameters:

• session –

• db_kb (DbKnowledgeBase) –

• xrefs (XRefManager) –

Returns:

static load(session, db_kb, kb, cfg_model=None)

Parameters:

• session –

• db_kb (DbKnowledgeBase) –

• kb (KnowledgeBase) –

• cfg_model (CFGModel) –

Returns:

class angr.angrdb.serializers.variables.VariableManagerSerializer

Bases: object

Serialize/unserialize a variable manager and its variables.

static dump(session, db_kb, var_manager)

Parameters:

• db_kb (DbKnowledgeBase) –

• var_manager (VariableManager) –

static dump_internal(session, db_kb, internal_manager, func_addr, ident=None)

Parameters:

• db_kb (DbKnowledgeBase) –

• internal_manager (VariableManagerInternal) –

• func_addr (int) –

static load(session, db_kb, kb, ident=None)

Parameters:

• db_kb (DbKnowledgeBase) –

• kb (KnowledgeBase) –

static load_internal(db_varcoll, variable_manager)

Return type:

VariableManagerInternal

Parameters:

variable_manager (VariableManager) –

class angr.angrdb.serializers.structured_code.StructuredCodeManagerSerializer

Bases: object

Serialize/unserialize a structured code manager.

static dump(session, db_kb, code_manager)

Parameters:

• session –

• db_kb (DbKnowledgeBase) –

• code_manager (StructuredCodeManager) –

Returns:

static dict_strkey_to_intkey(d)

Return type:

Dict[int, Any]

Parameters:

d (Dict[str, Any]) –

static load(session, db_kb, kb)

Parameters:

• session –

• db_kb (DbKnowledgeBase) –

• kb (KnowledgeBase) –

Return type:

StructuredCodeManager

Returns:

A loaded structured code manager

class angr.analyses.decompiler.structuring.recursive_structurer.RecursiveStructurer(region, cond_proc=None, func=None, structurer_cls=None, improve_structurer=True)

Bases: Analysis

Recursively structure a region and all of its subregions.

Parameters:

• func (Function | None) –

• structurer_cls (Type | None) –

__init__(region, cond_proc=None, func=None, structurer_cls=None, improve_structurer=True)

Parameters:

• func (Function | None) –

• structurer_cls (Type | None) –

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

angr.analyses.decompiler.structuring.structurer_class_from_name(name)

Return type:

Optional[Type]

Parameters:

name (str) –

class angr.analyses.decompiler.structuring.dream.DreamStructurer(region, parent_map=None, condition_processor=None, func=None, case_entry_to_switch_head=None, parent_region=None, improve_structurer=True)

Bases: StructurerBase

Structure a region using a structuring algorithm that is similar to the one in Dream decompiler (described in the “no more gotos” paper). Note that this implementation has quite a few improvements over the original described version and should not be used to evaluate the performance of the original algorithm described in that paper.

The current function graph is provided so that we can detect certain edge cases, for example, jump table entries no longer exist due to empty node removal during structuring or prior steps.

Parameters:

• func (Function | None) –

• case_entry_to_switch_head (Dict[int, int] | None) –

NAME: str = 'dream'

__init__(region, parent_map=None, condition_processor=None, func=None, case_entry_to_switch_head=None, parent_region=None, improve_structurer=True)

Parameters:

• func (Function | None) –

• case_entry_to_switch_head (Dict[int, int] | None) –

errors = []

static is_a_jump_target(stmt, addr)

Return type:

bool

Parameters:

• stmt (ConditionalJump | Jump) –

• addr (int) –

named_errors = {}

static replace_node_in_node(parent_node, old_node, new_node)

Return type:

None

Parameters:

• parent_node (BaseNode) –

• old_node (BaseNode | Block) –

• new_node (BaseNode | Block) –

static replace_nodes(graph, old_node_0, new_node, old_node_1=None, self_loop=True)

project: Project

kb: KnowledgeBase

exception angr.analyses.decompiler.structuring.structurer_nodes.EmptyBlockNotice

Bases: Exception

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class angr.analyses.decompiler.structuring.structurer_nodes.MultiNode(nodes, addr=None, idx=None)

Bases: object

__init__(nodes, addr=None, idx=None)

nodes

addr

idx

copy()

dbg_repr(indent=0)

class angr.analyses.decompiler.structuring.structurer_nodes.BaseNode

Bases: object

static test_empty_node(node)

static test_empty_condition_node(cond_node)

addr: Optional[int]

dbg_repr(indent=0)

class angr.analyses.decompiler.structuring.structurer_nodes.SequenceNode(addr, nodes=None)

Bases: BaseNode

Parameters:

addr (int | None) –

__init__(addr, nodes=None)

Parameters:

addr (int | None) –

addr: Optional[int]

nodes

add_node(node)

insert_node(pos, node)

remove_node(node)

node_position(node)

copy()

dbg_repr(indent=0)

static test_empty_condition_node(cond_node)

static test_empty_node(node)

class angr.analyses.decompiler.structuring.structurer_nodes.CodeNode(node, reaching_condition)

Bases: BaseNode

__init__(node, reaching_condition)

node

reaching_condition

property addr

property idx

dbg_repr(indent=0)

copy()

static test_empty_condition_node(cond_node)

static test_empty_node(node)

class angr.analyses.decompiler.structuring.structurer_nodes.ConditionNode(addr, reaching_condition, condition, true_node, false_node=None)

Bases: BaseNode

Parameters:

addr (int | None) –

__init__(addr, reaching_condition, condition, true_node, false_node=None)

addr: Optional[int]

reaching_condition

condition

true_node

false_node

dbg_repr(indent=0)

node

static test_empty_condition_node(cond_node)

static test_empty_node(node)

class angr.analyses.decompiler.structuring.structurer_nodes.CascadingConditionNode(addr, condition_and_nodes, else_node=None)

Bases: BaseNode

Parameters:

• addr (int | None) –

• condition_and_nodes (List[Tuple[Any, BaseNode]]) –

• else_node (BaseNode) –

__init__(addr, condition_and_nodes, else_node=None)

Parameters:

• condition_and_nodes (List[Tuple[Any, BaseNode]]) –

• else_node (BaseNode | None) –

addr: Optional[int]

condition_and_nodes

else_node

dbg_repr(indent=0)

static test_empty_condition_node(cond_node)

static test_empty_node(node)

class angr.analyses.decompiler.structuring.structurer_nodes.LoopNode(sort, condition, sequence_node, addr=None, continue_addr=None, initializer=None, iterator=None)

Bases: BaseNode

Parameters:

addr (int | None) –

__init__(sort, condition, sequence_node, addr=None, continue_addr=None, initializer=None, iterator=None)

sort

condition

sequence_node

initializer

iterator

copy()

property addr

property continue_addr

dbg_repr(indent=0)

static test_empty_condition_node(cond_node)

static test_empty_node(node)

class angr.analyses.decompiler.structuring.structurer_nodes.BreakNode(addr, target)

Bases: BaseNode

Parameters:

addr (int | None) –

__init__(addr, target)

addr: Optional[int]

target

dbg_repr(indent=0)

static test_empty_condition_node(cond_node)

static test_empty_node(node)

class angr.analyses.decompiler.structuring.structurer_nodes.ContinueNode(addr, target)

Bases: BaseNode

Parameters:

addr (int | None) –

__init__(addr, target)

addr: Optional[int]

target

dbg_repr(indent=0)

static test_empty_condition_node(cond_node)

static test_empty_node(node)

class angr.analyses.decompiler.structuring.structurer_nodes.ConditionalBreakNode(addr, condition, target)

Bases: BreakNode

Parameters:

addr (int | None) –

__init__(addr, condition, target)

condition

dbg_repr(indent=0)

addr: Optional[int]

target

static test_empty_condition_node(cond_node)

static test_empty_node(node)

class angr.analyses.decompiler.structuring.structurer_nodes.SwitchCaseNode(switch_expr, cases, default_node, addr=None)

Bases: BaseNode

Parameters:

• cases (OrderedDict[int | Tuple[int, ...], SequenceNode]) –

• addr (int | None) –

__init__(switch_expr, cases, default_node, addr=None)

Parameters:

cases (OrderedDict[int | Tuple[int, ...], SequenceNode]) –

switch_expr

cases: OrderedDict[Union[int, Tuple[int, ...]], SequenceNode]

default_node

addr: Optional[int]

dbg_repr(indent=0)

static test_empty_condition_node(cond_node)

static test_empty_node(node)

class angr.analyses.decompiler.structuring.structurer_nodes.IncompleteSwitchCaseNode(addr, head, cases)

Bases: BaseNode

Describes an incomplete set of switch-case nodes. Usually an intermediate result. Should always be restructured into a SwitchCaseNode by the end of structuring. Only used in Phoenix structurer.

Parameters:

• addr (int | None) –

• cases (List) –

__init__(addr, head, cases)

Parameters:

cases (List) –

addr: Optional[int]

head

cases: List

dbg_repr(indent=0)

static test_empty_condition_node(cond_node)

static test_empty_node(node)

class angr.analyses.decompiler.structuring.structurer_nodes.IncompleteSwitchCaseHeadStatement(*args, **kwargs)

Bases: Statement

Describes a switch-case head. This is only created by LoweredSwitchSimplifier.

__init__(idx, switch_variable, case_addrs, **kwargs)

switch_variable

case_addrs: List[Tuple[Block, Union[int, str], int, int]]

addr

eq(expr0, expr1)

idx

initialize_tags(tags)

replace(old_expr, new_expr)

property tags: Dict

class angr.analyses.decompiler.structuring.structurer_base.StructurerBase(region, parent_map=None, condition_processor=None, func=None, case_entry_to_switch_head=None, parent_region=None, improve_structurer=True)

Bases: Analysis

The base class for analysis passes that structures a region.

The current function graph is provided so that we can detect certain edge cases, for example, jump table entries no longer exist due to empty node removal during structuring or prior steps.

Parameters:

• func (Function | None) –

• case_entry_to_switch_head (Dict[int, int] | None) –

NAME: str = None

__init__(region, parent_map=None, condition_processor=None, func=None, case_entry_to_switch_head=None, parent_region=None, improve_structurer=True)

Parameters:

• func (Function | None) –

• case_entry_to_switch_head (Dict[int, int] | None) –

static replace_nodes(graph, old_node_0, new_node, old_node_1=None, self_loop=True)

static replace_node_in_node(parent_node, old_node, new_node)

Return type:

None

Parameters:

• parent_node (BaseNode) –

• old_node (BaseNode | Block) –

• new_node (BaseNode | Block) –

static is_a_jump_target(stmt, addr)

Return type:

bool

Parameters:

• stmt (ConditionalJump | Jump) –

• addr (int) –

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

exception angr.analyses.decompiler.structuring.phoenix.GraphChangedNotification

Bases: Exception

A notification for graph that is currently worked on being changed. Once this notification is caught, the graph schema matching process for the current region restarts.

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class angr.analyses.decompiler.structuring.phoenix.PhoenixStructurer(region, parent_map=None, condition_processor=None, func=None, case_entry_to_switch_head=None, parent_region=None, improve_structurer=True)

Bases: StructurerBase

Structure a region using a structuring algorithm that is similar to the one in Phoenix decompiler (described in the “phoenix decompiler” paper). Note that this implementation has quite a few improvements over the original described version and should not be used to evaluate the performance of the original algorithm described in that paper.

Parameters:

• func (Function | None) –

• case_entry_to_switch_head (Dict[int, int] | None) –

NAME: str = 'phoenix'

__init__(region, parent_map=None, condition_processor=None, func=None, case_entry_to_switch_head=None, parent_region=None, improve_structurer=True)

Parameters:

• func (Function | None) –

• case_entry_to_switch_head (Dict[int, int] | None) –

static dump_graph(graph, path)

Return type:

None

Parameters:

• graph (DiGraph) –

• path (str) –

errors = []

static is_a_jump_target(stmt, addr)

Return type:

bool

Parameters:

• stmt (ConditionalJump | Jump) –

• addr (int) –

named_errors = {}

static replace_node_in_node(parent_node, old_node, new_node)

Return type:

None

Parameters:

• parent_node (BaseNode) –

• old_node (BaseNode | Block) –

• new_node (BaseNode | Block) –

static replace_nodes(graph, old_node_0, new_node, old_node_1=None, self_loop=True)

project: Project

kb: KnowledgeBase

exception angr.analyses.decompiler.ail_simplifier.HasCallNotification

Bases: Exception

Notifies the existence of a call statement.

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class angr.analyses.decompiler.ail_simplifier.AILBlockTempCollector(**kwargs)

Bases: AILBlockWalker

Collects any temporaries used in a block.

__init__(**kwargs)

walk(block)

Parameters:

block (Block) –

walk_expression(expr, stmt_idx=None, stmt=None, block=None)

Parameters:

• expr (Expression) –

• stmt_idx (int | None) –

• stmt (int | None) –

• block (Block | None) –

walk_statement(stmt)

Parameters:

stmt (Statement) –

class angr.analyses.decompiler.ail_simplifier.ExpressionCounter(stmt, subexpr)

Bases: AILBlockWalkerBase

Count the occurrence of subexpr in expr.

__init__(stmt, subexpr)

walk(block)

Parameters:

block (Block) –

walk_expression(expr, stmt_idx=None, stmt=None, block=None)

Parameters:

• expr (Expression) –

• stmt_idx (int | None) –

• stmt (int | None) –

• block (Block | None) –

walk_statement(stmt)

Parameters:

stmt (Statement) –

class angr.analyses.decompiler.ail_simplifier.AILSimplifier(func, func_graph=None, remove_dead_memdefs=False, stack_arg_offsets=None, unify_variables=False, ail_manager=None, gp=None, narrow_expressions=False, only_consts=False, fold_callexprs_into_conditions=False)

Bases: Analysis

Perform function-level simplifications.

Parameters:

• stack_arg_offsets (Set[Tuple[int, int]] | None) –

• ail_manager (Manager | None) –

• gp (int | None) –

__init__(func, func_graph=None, remove_dead_memdefs=False, stack_arg_offsets=None, unify_variables=False, ail_manager=None, gp=None, narrow_expressions=False, only_consts=False, fold_callexprs_into_conditions=False)

Parameters:

• stack_arg_offsets (Set[Tuple[int, int]] | None) –

• ail_manager (Manager | None) –

• gp (int | None) –

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

exception angr.analyses.decompiler.ailgraph_walker.RemoveNodeNotice

Bases: Exception

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class angr.analyses.decompiler.ailgraph_walker.AILGraphWalker(graph, handler, replace_nodes=False)

Bases: object

Walks an AIL graph and optionally replaces each node with a new node.

Parameters:

replace_nodes (bool) –

__init__(graph, handler, replace_nodes=False)

Parameters:

replace_nodes (bool) –

walk()

class angr.analyses.decompiler.block_simplifier.BlockSimplifier(block, func_addr=None, remove_dead_memdefs=False, stack_pointer_tracker=None, peephole_optimizations=None, stack_arg_offsets=None, cached_reaching_definitions=None, cached_propagator=None)

Bases: Analysis

Simplify an AIL block.

Parameters:

• block (Block | None) –

• func_addr (int | None) –

• peephole_optimizations (Iterable[Type[PeepholeOptimizationStmtBase] | Type[PeepholeOptimizationExprBase]] | None) –

• stack_arg_offsets (Set[Tuple[int, int]] | None) –

__init__(block, func_addr=None, remove_dead_memdefs=False, stack_pointer_tracker=None, peephole_optimizations=None, stack_arg_offsets=None, cached_reaching_definitions=None, cached_propagator=None)

Parameters:

• block (Optional[Block]) – The AIL block to simplify. Setting it to None to skip calling self._analyze(), which is useful in test cases.

• func_addr (int | None) –

• peephole_optimizations (Iterable[Type[PeepholeOptimizationStmtBase] | Type[PeepholeOptimizationExprBase]] | None) –

• stack_arg_offsets (Set[Tuple[int, int]] | None) –

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

class angr.analyses.decompiler.callsite_maker.CallSiteMaker(block, reaching_definitions=None, stack_pointer_tracker=None, ail_manager=None)

Bases: Analysis

Add calling convention, declaration, and args to a call site.

__init__(block, reaching_definitions=None, stack_pointer_tracker=None, ail_manager=None)

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

class angr.analyses.decompiler.ccall_rewriters.rewriter_base.CCallRewriterBase(ccall, arch)

Bases: object

The base class for CCall rewriters.

Parameters:

ccall (VEXCCallExpression) –

__init__(ccall, arch)

Parameters:

ccall (VEXCCallExpression) –

arch

result: Optional[Expression]

class angr.analyses.decompiler.ccall_rewriters.amd64_ccalls.AMD64CCallRewriter(ccall, arch)

Bases: CCallRewriterBase

Implements ccall rewriter for AMD64.

Parameters:

ccall (VEXCCallExpression) –

__init__(ccall, arch)

Parameters:

ccall (VEXCCallExpression) –

arch

result: Optional[ailment.Expr.Expression]

class angr.analyses.decompiler.clinic.BlockCache(rd, prop)

Bases: tuple

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

prop

Alias for field number 1

rd

Alias for field number 0

class angr.analyses.decompiler.clinic.Clinic(func, remove_dead_memdefs=False, exception_edges=False, sp_tracker_track_memory=True, fold_callexprs_into_conditions=False, insert_labels=True, optimization_passes=None, cfg=None, peephole_optimizations=None, must_struct=None, variable_kb=None, reset_variable_names=False, cache=None)

Bases: Analysis

A Clinic deals with AILments.

Parameters:

• peephole_optimizations (Iterable[Type[PeepholeOptimizationStmtBase] | Type[PeepholeOptimizationExprBase]] | None) –

• must_struct (Set[str] | None) –

• cache (DecompilationCache | None) –

__init__(func, remove_dead_memdefs=False, exception_edges=False, sp_tracker_track_memory=True, fold_callexprs_into_conditions=False, insert_labels=True, optimization_passes=None, cfg=None, peephole_optimizations=None, must_struct=None, variable_kb=None, reset_variable_names=False, cache=None)

Parameters:

• peephole_optimizations (Iterable[Type[PeepholeOptimizationStmtBase] | Type[PeepholeOptimizationExprBase]] | None) –

• must_struct (Set[str] | None) –

• cache (DecompilationCache | None) –

block(addr, size)

Get the converted block at the given specific address with the given size.

Parameters:

• addr (int) –

• size (int) –

Returns:

dbg_repr()

Returns:

copy_graph()

Copy AIL Graph.

Return type:

DiGraph

Returns:

A copy of the AIl graph.

parse_variable_addr(addr)

Return type:

Optional[Tuple[Any, Any]]

Parameters:

addr (Expression) –

new_block_addr()

Return a block address that does not conflict with any existing blocks.

Return type:

int

Returns:

The block address.

errors = []

named_errors = {}

static remove_empty_nodes(graph)

Return type:

DiGraph

Parameters:

graph (DiGraph) –

project: Project

kb: KnowledgeBase

class angr.analyses.decompiler.condition_processor.ConditionProcessor(arch, condition_mapping=None)

Bases: object

Convert between claripy AST and AIL expressions. Also calculates reaching conditions of all nodes on a graph.

__init__(arch, condition_mapping=None)

clear()

recover_edge_condition(graph, src, dst)

Parameters:

graph (DiGraph) –

recover_edge_conditions(region, graph=None)

Return type:

Dict

recover_reaching_conditions(region, graph=None, with_successors=False, case_entry_to_switch_head=None)

Parameters:

case_entry_to_switch_head (Dict[int, int] | None) –

remove_claripy_bool_asts(node, memo=None)

classmethod get_last_statement(block)

This is the buggy version of get_last_statements, because, you know, there can always be more than one last statement due to the existence of branching statements (like, If-then-else). All methods using get_last_statement() should switch to get_last_statements() and properly handle multiple last statements.

classmethod get_last_statements(block)

Return type:

List[Optional[Statement]]

EXC_COUNTER = 1000

convert_claripy_bool_ast(cond, memo=None)

Convert recovered reaching conditions from claripy ASTs to ailment Expressions

Returns:

None

convert_claripy_bool_ast_core(cond, memo)

claripy_ast_from_ail_condition(condition, nobool=False)

Return type:

Bool

Parameters:

nobool (bool) –

static claripy_ast_to_sympy_expr(ast, memo=None)

static sympy_expr_to_claripy_ast(expr, memo)

Parameters:

memo (Dict) –

static simplify_condition(cond, depth_limit=8, variables_limit=8)

static simplify_condition_deprecated(cond)

create_jump_target_var(jumptable_head_addr)

Parameters:

jumptable_head_addr (int) –

class angr.analyses.decompiler.decompilation_options.DecompilationOption(name, description, value_type, cls, param, value_range=None, category='General', default_value=None, clears_cache=True, candidate_values=None, convert=None)

Bases: object

Describes a decompilation option.

Parameters:

• candidate_values (List | None) –

• convert (Callable | None) –

__init__(name, description, value_type, cls, param, value_range=None, category='General', default_value=None, clears_cache=True, candidate_values=None, convert=None)

Parameters:

• candidate_values (List | None) –

• convert (Callable | None) –

angr.analyses.decompiler.decompilation_options.O

alias of DecompilationOption

angr.analyses.decompiler.decompilation_options.get_structurer_option()

Return type:

Optional[DecompilationOption]

class angr.analyses.decompiler.decompilation_cache.DecompilationCache(addr)

Bases: object

Caches key data structures that can be used later for refining decompilation results, such as retyping variables.

__init__(addr)

addr

type_constraints: Optional[Set]

var_to_typevar: Optional[Dict]

codegen: Optional[BaseStructuredCodeGenerator]

clinic: Optional[Clinic]

ite_exprs: Optional[Set[Tuple[int, Any]]]

binop_operators: Optional[Dict[OpDescriptor, str]]

property local_types

class angr.analyses.decompiler.decompiler.Decompiler(func, cfg=None, options=None, optimization_passes=None, sp_tracker_track_memory=True, variable_kb=None, peephole_optimizations=None, vars_must_struct=None, flavor='pseudocode', expr_comments=None, stmt_comments=None, ite_exprs=None, binop_operators=None, decompile=True, regen_clinic=True, update_memory_data=True)

Bases: Analysis

The decompiler analysis.

Run this on a Function object for which a normalized CFG has been constructed. The fully processed output can be found in result.codegen.text

Parameters:

• func (Function | str | int) –

• cfg (CFGFast | CFGModel | None) –

• peephole_optimizations (Iterable[Type[PeepholeOptimizationStmtBase] | Type[PeepholeOptimizationExprBase]] | None) –

• vars_must_struct (Set[str] | None) –

• update_memory_data (bool) –

__init__(func, cfg=None, options=None, optimization_passes=None, sp_tracker_track_memory=True, variable_kb=None, peephole_optimizations=None, vars_must_struct=None, flavor='pseudocode', expr_comments=None, stmt_comments=None, ite_exprs=None, binop_operators=None, decompile=True, regen_clinic=True, update_memory_data=True)

Parameters:

• func (Function | str | int) –

• cfg (CFGFast | CFGModel | None) –

• peephole_optimizations (Iterable[Type[PeepholeOptimizationStmtBase] | Type[PeepholeOptimizationExprBase]] | None) –

• vars_must_struct (Set[str] | None) –

• update_memory_data (bool) –

reflow_variable_types(type_constraints, var_to_typevar, codegen)

Re-run type inference on an existing variable recovery result, then rerun codegen to generate new results.

Returns:

Parameters:

• type_constraints (Set) –

• var_to_typevar (Dict) –

find_data_references_and_update_memory_data(seq_node)

Parameters:

seq_node (SequenceNode) –

errors = []

named_errors = {}

static options_to_params(options)

Convert decompilation options to a dict of params.

Parameters:

options (List[Tuple[DecompilationOption, Any]]) – The decompilation options.

Return type:

Dict[str, Any]

Returns:

A dict of keyword arguments.

project: Project

kb: KnowledgeBase

class angr.analyses.decompiler.empty_node_remover.EmptyNodeRemover(node, claripy_ast_conditions=True)

Bases: object

Rewrites a node and its children to remove empty nodes.

The following optimizations are performed at the same time: - Convert if (A) { } else { … } to if(!A) { … } else { }

Variables:

_claripy_ast_conditions – True if all node conditions are claripy ASTs. False if all node conditions are AIL expressions.

Parameters:

claripy_ast_conditions (bool) –

__init__(node, claripy_ast_conditions=True)

Parameters:

claripy_ast_conditions (bool) –

class angr.analyses.decompiler.expression_narrower.ExpressionNarrowingWalker(target_expr)

Bases: AILBlockWalkerBase

Walks a statement or an expression and extracts the operations that are applied on the given expression.

For example, for target expression rax, (rax & 0xff) + 0x1 means the following operations are applied on rax: rax & 0xff (rax & 0xff) + 0x1

The previous expression is always used in the succeeding expression.

Parameters:

target_expr (Expression) –

__init__(target_expr)

Parameters:

target_expr (Expression) –

walk(block)

Parameters:

block (Block) –

walk_expression(expr, stmt_idx=None, stmt=None, block=None)

Parameters:

• expr (Expression) –

• stmt_idx (int | None) –

• stmt (int | None) –

• block (Block | None) –

walk_statement(stmt)

Parameters:

stmt (Statement) –

class angr.analyses.decompiler.graph_region.GraphRegion(head, graph, successors, graph_with_successors, cyclic, full_graph, cyclic_ancestor=False)

Bases: object

GraphRegion represents a region of nodes.

Variables:

• head – The head of the region.

• graph – The region graph.

• successors – A set of successors of nodes in the graph. These successors do not belong to the current region.

• graph_with_successors – The region graph that includes successor nodes.

Parameters:

• successors (Set | None) –

• graph_with_successors (DiGraph | None) –

• full_graph (DiGraph | None) –

• cyclic_ancestor (bool) –

__init__(head, graph, successors, graph_with_successors, cyclic, full_graph, cyclic_ancestor=False)

Parameters:

• successors (Set | None) –

• graph_with_successors (DiGraph | None) –

• full_graph (DiGraph | None) –

• cyclic_ancestor (bool) –

head

graph

successors

graph_with_successors

full_graph

cyclic

cyclic_ancestor

copy()

Return type:

GraphRegion

recursive_copy(nodes_map=None)

property addr

static dbg_get_repr(obj, ident=0)

dbg_print(ident=0)

replace_region(sub_region, updated_sub_region, replace_with)

Parameters:

• sub_region (GraphRegion) –

• updated_sub_region (GraphRegion) –

replace_region_with_region(sub_region, replace_with)

Parameters:

• sub_region (GraphRegion) –

• replace_with (GraphRegion) –

class angr.analyses.decompiler.jump_target_collector.JumpTargetCollector(node)

Bases: object

Collect all jump targets.

__init__(node)

class angr.analyses.decompiler.jumptable_entry_condition_rewriter.JumpTableEntryConditionRewriter(jumptable_entry_conds)

Bases: SequenceWalker

Remove artificial jump table entry conditions that ConditionProcessor introduced when dealing with jump tables.

__init__(jumptable_entry_conds)

walk(sequence)

angr.analyses.decompiler.optimization_passes.get_optimization_passes(arch, platform)

angr.analyses.decompiler.optimization_passes.get_default_optimization_passes(arch, platform)

Parameters:

• arch (Arch | str) –

• platform (str | None) –

class angr.analyses.decompiler.optimization_passes.const_derefs.BlockWalker(project)

Bases: AILBlockWalker

Parameters:

project (Project) –

__init__(project)

Parameters:

project (Project) –

walk(block)

Parameters:

block (Block) –

walk_expression(expr, stmt_idx=None, stmt=None, block=None)

Parameters:

• expr (Expression) –

• stmt_idx (int | None) –

• stmt (int | None) –

• block (Block | None) –

walk_statement(stmt)

Parameters:

stmt (Statement) –

class angr.analyses.decompiler.optimization_passes.const_derefs.ConstantDereferencesSimplifier(func, **kwargs)

Bases: OptimizationPass

Makes the following simplifications:

*(*(const_addr))  ==>  *(value) iff  *const_addr == value

ARCHES = ['X86', 'AMD64', 'ARMEL', 'ARMHF', 'ARMCortexM', 'MIPS32', 'MIPS64']

PLATFORMS = ['linux']

STAGE: int = 2

NAME = 'Simplify constant dereferences'

DESCRIPTION = 'Makes the following simplifications::\n\n        *(*(const_addr))  ==>  *(value) iff  *const_addr == value'

__init__(func, **kwargs)

STRUCTURING: Optional[str] = None

analyze()

property blocks_by_addr: Dict[int, Set[Block]]

property blocks_by_addr_and_idx: Dict[Tuple[int, int | None], Block]

property kb

property project

class angr.analyses.decompiler.optimization_passes.eager_returns.EagerReturnsSimplifier(func, blocks_by_addr=None, blocks_by_addr_and_idx=None, graph=None, node_idx_start=0, max_level=2, min_indegree=2, reaching_definitions=None, **kwargs)

Bases: OptimizationPass

Some compilers (if not all) generate only one returning block for a function regardless of how many returns there are in the source code. This oftentimes result in irreducible graphs and reduce the readability of the decompiled code. This optimization pass will make the function return eagerly by duplicating the return site of a function multiple times and assigning one copy of the return site to each of its sources when certain thresholds are met.

Note that this simplifier may reduce the readability of the generated code in certain cases, especially if the graph is already reducible without applying this simplifier.

Variables:

• max_level (int) – Number of times that we repeat the process of making returns eager.

• min_indegree (int) – The minimum in-degree of the return site to be duplicated.

• node_idx – The next node index. Each duplicated return site gets assigned a unique index, otherwise those duplicates will be considered as the same block in the graph because they have the same hash.

ARCHES = ['X86', 'AMD64', 'ARMCortexM', 'ARMHF', 'ARMEL']

PLATFORMS = ['cgc', 'linux']

STAGE: int = 0

NAME = 'Duplicate return blocks to reduce goto statements'

DESCRIPTION = 'Some compilers (if not all) generate only one returning block for a function regardless of how many returns there\nare in the source code. This oftentimes result in irreducible graphs and reduce the readability of the decompiled\ncode. This optimization pass will make the function return eagerly by duplicating the return site of a function\nmultiple times and assigning one copy of the return site to each of its sources when certain thresholds are met.\n\nNote that this simplifier may reduce the readability of the generated code in certain cases, especially if the graph\nis already reducible without applying this simplifier.'

__init__(func, blocks_by_addr=None, blocks_by_addr_and_idx=None, graph=None, node_idx_start=0, max_level=2, min_indegree=2, reaching_definitions=None, **kwargs)

STRUCTURING: Optional[str] = None

analyze()

property blocks_by_addr: Dict[int, Set[Block]]

property blocks_by_addr_and_idx: Dict[Tuple[int, int | None], Block]

property kb

property project

exception angr.analyses.decompiler.optimization_passes.optimization_pass.MultipleBlocksException

Bases: Exception

An exception that is raised in _get_block() where multiple blocks satisfy the criteria but only one block was requested.

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class angr.analyses.decompiler.optimization_passes.optimization_pass.OptimizationPassStage(value)

Bases: Enum

Enums about optimization pass stages.

Note that the region identification pass (RegionIdentifier) may modify existing AIL blocks without updating the topology of the original AIL graph. For example, loop successor refinement may modify create a new AIL block with an artificial address, and alter existing jump targets of jump statements and conditional jump statements to point to this new block. However, loop successor refinement does not update the topology of the original AIL graph, which means this new AIL block does not exist in the original AIL graph. As a result, until this behavior of RegionIdentifier changes in the future, DURING_REGION_IDENTIFICATION optimization passes should not modify existing jump targets.

AFTER_AIL_GRAPH_CREATION = 0

AFTER_SINGLE_BLOCK_SIMPLIFICATION = 1

AFTER_GLOBAL_SIMPLIFICATION = 2

AFTER_VARIABLE_RECOVERY = 3

BEFORE_REGION_IDENTIFICATION = 4

DURING_REGION_IDENTIFICATION = 5

AFTER_STRUCTURING = 6

class angr.analyses.decompiler.optimization_passes.optimization_pass.BaseOptimizationPass(func)

Bases: object

The base class for any optimization pass.

ARCHES = []

PLATFORMS = []

STAGE: int = None

STRUCTURING: Optional[str] = None

__init__(func)

property project

property kb

analyze()

class angr.analyses.decompiler.optimization_passes.optimization_pass.OptimizationPass(func, blocks_by_addr=None, blocks_by_addr_and_idx=None, graph=None, variable_kb=None, region_identifier=None, reaching_definitions=None, **kwargs)

Bases: BaseOptimizationPass

The base class for any function-level graph optimization pass.

__init__(func, blocks_by_addr=None, blocks_by_addr_and_idx=None, graph=None, variable_kb=None, region_identifier=None, reaching_definitions=None, **kwargs)

property blocks_by_addr: Dict[int, Set[Block]]

property blocks_by_addr_and_idx: Dict[Tuple[int, int | None], Block]

ARCHES = []

PLATFORMS = []

STAGE: int = None

STRUCTURING: Optional[str] = None

analyze()

property kb

property project

class angr.analyses.decompiler.optimization_passes.optimization_pass.SequenceOptimizationPass(func, seq=None, **kwargs)

Bases: BaseOptimizationPass

The base class for any sequence node optimization pass.

ARCHES = []

PLATFORMS = []

STAGE: int = None

__init__(func, seq=None, **kwargs)

STRUCTURING: Optional[str] = None

analyze()

property kb

property project

angr.analyses.decompiler.optimization_passes.stack_canary_simplifier.s2u(s, bits)

class angr.analyses.decompiler.optimization_passes.stack_canary_simplifier.StackCanarySimplifier(func, **kwargs)

Bases: OptimizationPass

Removes stack canary checks from decompilation results.

ARCHES = ['X86', 'AMD64']

PLATFORMS = ['cgc', 'linux']

STAGE: int = 2

NAME = 'Simplify stack canaries'

DESCRIPTION = 'Removes stack canary checks from decompilation results.'

__init__(func, **kwargs)

STRUCTURING: Optional[str] = None

analyze()

property blocks_by_addr: Dict[int, Set[Block]]

property blocks_by_addr_and_idx: Dict[Tuple[int, int | None], Block]

property kb

property project

out_graph: Optional[networkx.DiGraph]

class angr.analyses.decompiler.optimization_passes.base_ptr_save_simplifier.BasePointerSaveSimplifier(func, **kwargs)

Bases: OptimizationPass

Removes the effects of base pointer stack storage at function invocation and restoring at function return.

ARCHES = ['X86', 'AMD64', 'ARMEL', 'ARMHF', 'ARMCortexM', 'MIPS32', 'MIPS64']

PLATFORMS = ['cgc', 'linux']

STAGE: int = 2

NAME = 'Simplify base pointer saving'

DESCRIPTION = 'Removes the effects of base pointer stack storage at function invocation and restoring at function return.'

__init__(func, **kwargs)

STRUCTURING: Optional[str] = None

analyze()

property blocks_by_addr: Dict[int, Set[Block]]

property blocks_by_addr_and_idx: Dict[Tuple[int, int | None], Block]

property kb

property project

out_graph: Optional[networkx.DiGraph]

class angr.analyses.decompiler.optimization_passes.div_simplifier.DivSimplifierAILEngine

Bases: SimplifierAILEngine

An AIL pass for the div simplifier

__init__()

static extract_offset_to_sp(spoffset_expr)

Extract the offset to the original stack pointer.

Parameters:

spoffset_expr (Base) – The claripy AST to parse.

Return type:

Optional[int]

Returns:

The offset to the original stack pointer, or None if spoffset_expr is not a supported type of SpOffset expression.

process(state, *args, **kwargs)

The main entry point for an engine. Should take a state and return a result.

Parameters:

state – The state to proceed from

Returns:

The result. Whatever you want ;)

static sp_offset(bits, offset)

Parameters:

• bits (int) –

• offset (int) –

class angr.analyses.decompiler.optimization_passes.div_simplifier.DivSimplifier(func, **kwargs)

Bases: OptimizationPass

Simplifies various division optimizations back to “div”.

ARCHES = ['X86', 'AMD64', 'ARMCortexM', 'ARMHF', 'ARMEL']

PLATFORMS = None

STAGE: int = 2

NAME = 'Simplify arithmetic division'

DESCRIPTION = 'Simplifies various division optimizations back to "div".'

__init__(func, **kwargs)

STRUCTURING: Optional[str] = None

analyze()

property blocks_by_addr: Dict[int, Set[Block]]

property blocks_by_addr_and_idx: Dict[Tuple[int, int | None], Block]

property kb

property project

out_graph: Optional[networkx.DiGraph]

exception angr.analyses.decompiler.optimization_passes.ite_expr_converter.NodeFoundNotification

Bases: Exception

A notification that the target node has been found.

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class angr.analyses.decompiler.optimization_passes.ite_expr_converter.BlockLocator(block)

Bases: RegionWalker

Recursively locate block in a GraphRegion instance.

It might be reasonable to move this class into its own file.

__init__(block)

walk_node(region, node)

walk(region)

Parameters:

region (GraphRegion) –

class angr.analyses.decompiler.optimization_passes.ite_expr_converter.ExpressionReplacer(block_addr, target_expr, callback)

Bases: AILBlockWalker

Replace expressions.

__init__(block_addr, target_expr, callback)

walk(block)

Parameters:

block (Block) –

walk_expression(expr, stmt_idx=None, stmt=None, block=None)

Parameters:

• expr (Expression) –

• stmt_idx (int | None) –

• stmt (int | None) –

• block (Block | None) –

walk_statement(stmt)

Parameters:

stmt (Statement) –

class angr.analyses.decompiler.optimization_passes.ite_expr_converter.ITEExprConverter(func, ite_exprs=None, **kwargs)

Bases: OptimizationPass

Transform specific expressions into If-Then-Else expressions, or tertiary expressions in C.

ARCHES = ['X86', 'AMD64', 'ARMEL', 'ARMHF', 'ARMCortexM', 'MIPS32', 'MIPS64']

PLATFORMS = ['windows', 'linux', 'cgc']

STAGE: int = 5

NAME = 'Transform expressions that were assigned to in different If-Else branches into ternary expressions'

DESCRIPTION = 'Transform specific expressions into If-Then-Else expressions, or tertiary expressions in C.'

__init__(func, ite_exprs=None, **kwargs)

STRUCTURING: Optional[str] = None

analyze()

property blocks_by_addr: Dict[int, Set[Block]]

property blocks_by_addr_and_idx: Dict[Tuple[int, int | None], Block]

property kb

property project

out_graph: Optional[networkx.DiGraph]

class angr.analyses.decompiler.optimization_passes.lowered_switch_simplifier.Case(original_node, node_type, variable_hash, expr, value, target, next_addr)

Bases: object

Describes a case in a switch-case construct.

Parameters:

• node_type (str | None) –

• value (int | str) –

__init__(original_node, node_type, variable_hash, expr, value, target, next_addr)

Parameters:

• node_type (str | None) –

• value (int | str) –

original_node

node_type

variable_hash

expr

value

target

next_addr

class angr.analyses.decompiler.optimization_passes.lowered_switch_simplifier.StableVarExprHasher(expr)

Bases: AILBlockWalkerBase

Obtain a stable hash of an AIL expression with respect to all variables and all operations applied on variables.

Parameters:

expr (Expression) –

__init__(expr)

Parameters:

expr (Expression) –

walk(block)

Parameters:

block (Block) –

walk_expression(expr, stmt_idx=None, stmt=None, block=None)

Parameters:

• expr (Expression) –

• stmt_idx (int | None) –

• stmt (int | None) –

• block (Block | None) –

walk_statement(stmt)

Parameters:

stmt (Statement) –

class angr.analyses.decompiler.optimization_passes.lowered_switch_simplifier.LoweredSwitchSimplifier(func, blocks_by_addr=None, blocks_by_addr_and_idx=None, graph=None, **kwargs)

Bases: OptimizationPass

Recognize and simplify lowered switch-case constructs.

ARCHES = ['AMD64']

PLATFORMS = ['linux', 'windows']

STAGE: int = 4

NAME = 'Convert lowered switch-cases (if-else) to switch-cases'

DESCRIPTION = 'Convert lowered switch-cases (if-else) to switch-cases. Only works when the Phoenix structuring algorithm is in use.'

STRUCTURING: Optional[str] = ['phoenix']

__init__(func, blocks_by_addr=None, blocks_by_addr_and_idx=None, graph=None, **kwargs)

static restore_graph(node, last_stmt, graph, full_graph)

Parameters:

• last_stmt (IncompleteSwitchCaseHeadStatement) –

• graph (DiGraph) –

• full_graph (DiGraph) –

static cases_issubset(cases_0, cases_1)

Test if cases_0 is a subset of cases_1.

Return type:

bool

Parameters:

• cases_0 (List[Case]) –

• cases_1 (List[Case]) –

analyze()

property blocks_by_addr: Dict[int, Set[Block]]

property blocks_by_addr_and_idx: Dict[Tuple[int, int | None], Block]

property kb

property project

out_graph: Optional[networkx.DiGraph]

class angr.analyses.decompiler.optimization_passes.multi_simplifier.MultiSimplifierAILEngine

Bases: SimplifierAILEngine

An AIL pass for the multi simplifier

__init__()

static extract_offset_to_sp(spoffset_expr)

Extract the offset to the original stack pointer.

Parameters:

spoffset_expr (Base) – The claripy AST to parse.

Return type:

Optional[int]

Returns:

The offset to the original stack pointer, or None if spoffset_expr is not a supported type of SpOffset expression.

process(state, *args, **kwargs)

The main entry point for an engine. Should take a state and return a result.

Parameters:

state – The state to proceed from

Returns:

The result. Whatever you want ;)

static sp_offset(bits, offset)

Parameters:

• bits (int) –

• offset (int) –

class angr.analyses.decompiler.optimization_passes.multi_simplifier.MultiSimplifier(func, **kwargs)

Bases: OptimizationPass

Implements several different arithmetic optimizations.

ARCHES = ['X86', 'AMD64']

PLATFORMS = ['linux', 'windows']

STAGE: int = 2

NAME = 'Simplify various arithmetic expressions'

DESCRIPTION = 'Implements several different arithmetic optimizations.'

__init__(func, **kwargs)

STRUCTURING: Optional[str] = None

analyze()

property blocks_by_addr: Dict[int, Set[Block]]

property blocks_by_addr_and_idx: Dict[Tuple[int, int | None], Block]

property kb

property project

out_graph: Optional[networkx.DiGraph]

class angr.analyses.decompiler.optimization_passes.mod_simplifier.ModSimplifierAILEngine

Bases: SimplifierAILEngine

__init__()

static extract_offset_to_sp(spoffset_expr)

Extract the offset to the original stack pointer.

Parameters:

spoffset_expr (Base) – The claripy AST to parse.

Return type:

Optional[int]

Returns:

The offset to the original stack pointer, or None if spoffset_expr is not a supported type of SpOffset expression.

process(state, *args, **kwargs)

The main entry point for an engine. Should take a state and return a result.

Parameters:

state – The state to proceed from

Returns:

The result. Whatever you want ;)

static sp_offset(bits, offset)

Parameters:

• bits (int) –

• offset (int) –

class angr.analyses.decompiler.optimization_passes.mod_simplifier.ModSimplifier(func, **kwargs)

Bases: OptimizationPass

Simplifies optimized forms of modulo computation back to “mod”.

ARCHES = ['X86', 'AMD64', 'ARMCortexM', 'ARMHF', 'ARMEL']

PLATFORMS = ['linux', 'windows']

STAGE: int = 2

NAME = 'Simplify optimized mod forms'

DESCRIPTION = 'Simplifies optimized forms of modulo computation back to "mod".'

__init__(func, **kwargs)

STRUCTURING: Optional[str] = None

analyze()

property blocks_by_addr: Dict[int, Set[Block]]

property blocks_by_addr_and_idx: Dict[Tuple[int, int | None], Block]

property kb

property project

out_graph: Optional[networkx.DiGraph]

class angr.analyses.decompiler.optimization_passes.engine_base.SimplifierAILState(arch, variables=None)

Bases: object

The abstract state used in SimplifierAILEngine.

__init__(arch, variables=None)

copy()

merge(*others)

store_variable(old, new)

get_variable(old)

remove_variable(old)

filter_variables(atom)

class angr.analyses.decompiler.optimization_passes.engine_base.SimplifierAILEngine

Bases: SimEngineLightAILMixin, SimEngineLight

Essentially implements a peephole optimization engine for AIL statements (because we do not perform memory or register loads).

__init__()

process(state, *args, **kwargs)

The main entry point for an engine. Should take a state and return a result.

Parameters:

state – The state to proceed from

Returns:

The result. Whatever you want ;)

static extract_offset_to_sp(spoffset_expr)

Extract the offset to the original stack pointer.

Parameters:

spoffset_expr (Base) – The claripy AST to parse.

Return type:

Optional[int]

Returns:

The offset to the original stack pointer, or None if spoffset_expr is not a supported type of SpOffset expression.

static sp_offset(bits, offset)

Parameters:

• bits (int) –

• offset (int) –

class angr.analyses.decompiler.optimization_passes.expr_op_swapper.OuterWalker(desc)

Bases: SequenceWalker

A sequence walker that finds nodes and invokes expression replacer to replace expressions.

__init__(desc)

walk(sequence)

class angr.analyses.decompiler.optimization_passes.expr_op_swapper.ExpressionReplacer(block_addr, target_expr_predicate, callback)

Bases: AILBlockWalker

Replace expressions.

__init__(block_addr, target_expr_predicate, callback)

walk(block)

Parameters:

block (Block) –

walk_expression(expr, stmt_idx=None, stmt=None, block=None)

Parameters:

• expr (Expression) –

• stmt_idx (int | None) –

• stmt (int | None) –

• block (Block | None) –

walk_statement(stmt)

Parameters:

stmt (Statement) –

class angr.analyses.decompiler.optimization_passes.expr_op_swapper.OpDescriptor(block_addr, stmt_idx, ins_addr, op)

Bases: object

Describes a specific operator.

Parameters:

• block_addr (int) –

• stmt_idx (int) –

• ins_addr (int) –

• op (str) –

__init__(block_addr, stmt_idx, ins_addr, op)

Parameters:

• block_addr (int) –

• stmt_idx (int) –

• ins_addr (int) –

• op (str) –

class angr.analyses.decompiler.optimization_passes.expr_op_swapper.ExprOpSwapper(func, binop_operators=None, **kwargs)

Bases: SequenceOptimizationPass

Swap operands (and the operator accordingly) in a BinOp expression.

Parameters:

binop_operators (Dict[OpDescriptor, str] | None) –

ARCHES = ['X86', 'AMD64', 'ARMEL', 'ARMHF', 'ARMCortexM', 'MIPS32', 'MIPS64']

PLATFORMS = ['windows', 'linux', 'cgc']

STAGE: int = 6

NAME = 'Swap operands of expressions as requested'

DESCRIPTION = 'Swap operands (and the operator accordingly) in a BinOp expression.'

__init__(func, binop_operators=None, **kwargs)

Parameters:

binop_operators (Dict[OpDescriptor, str] | None) –

STRUCTURING: Optional[str] = None

analyze()

property kb

property project

angr.analyses.decompiler.optimization_passes.register_save_area_simplifier.s2u(s, bits)

class angr.analyses.decompiler.optimization_passes.register_save_area_simplifier.RegisterSaveAreaSimplifier(func, **kwargs)

Bases: OptimizationPass

Optimizes away register spilling effects, including callee-saved registers.

ARCHES = ['X86', 'AMD64', 'ARM', 'ARMEL', 'ARMHF', 'ARMCortexM', 'MIPS32', 'MIPS64']

PLATFORMS = ['cgc', 'linux']

STAGE: int = 2

NAME = 'Simplify register save areas'

DESCRIPTION = 'Optimizes away register spilling effects, including callee-saved registers.'

__init__(func, **kwargs)

STRUCTURING: Optional[str] = None

analyze()

property blocks_by_addr: Dict[int, Set[Block]]

property blocks_by_addr_and_idx: Dict[Tuple[int, int | None], Block]

property kb

property project

out_graph: Optional[networkx.DiGraph]

class angr.analyses.decompiler.optimization_passes.ret_addr_save_simplifier.RetAddrSaveSimplifier(func, **kwargs)

Bases: OptimizationPass

Removes code in function prologues and epilogues for saving and restoring return address registers (ra, lr, etc.), generally seen in non-leaf functions.

ARCHES = ['MIPS32', 'MIPS64']

PLATFORMS = ['linux']

STAGE: int = 2

NAME = 'Simplify return address storage'

DESCRIPTION = 'Removes code in function prologues and epilogues for saving and restoring return address registers (ra, lr, etc.),\n    generally seen in non-leaf functions.'

__init__(func, **kwargs)

STRUCTURING: Optional[str] = None

analyze()

property blocks_by_addr: Dict[int, Set[Block]]

property blocks_by_addr_and_idx: Dict[Tuple[int, int | None], Block]

property kb

property project

out_graph: Optional[networkx.DiGraph]

class angr.analyses.decompiler.optimization_passes.x86_gcc_getpc_simplifier.X86GccGetPcSimplifier(func, **kwargs)

Bases: OptimizationPass

Simplifies __x86.get_pc_thunk calls.

ARCHES = ['X86']

PLATFORMS = ['linux']

STAGE: int = 1

NAME = 'Simplify getpc()'

DESCRIPTION = 'Simplifies __x86.get_pc_thunk calls.'

__init__(func, **kwargs)

STRUCTURING: Optional[str] = None

analyze()

property blocks_by_addr: Dict[int, Set[Block]]

property blocks_by_addr_and_idx: Dict[Tuple[int, int | None], Block]

property kb

property project

out_graph: Optional[networkx.DiGraph]

class angr.analyses.decompiler.peephole_optimizations.base.PeepholeOptimizationStmtBase(project, kb, func_addr=None)

Bases: object

The base class for all peephole optimizations that are applied on AIL statements.

Parameters:

• project (Project | None) –

• kb (KnowledgeBase | None) –

• func_addr (int | None) –

NAME = 'Peephole Optimization - Statement'

DESCRIPTION = 'Peephole Optimization - Statement'

stmt_classes = None

__init__(project, kb, func_addr=None)

Parameters:

• project (Project | None) –

• kb (KnowledgeBase | None) –

• func_addr (int | None) –

project: Optional[Project]

kb: Optional[KnowledgeBase]

func_addr: Optional[int]

optimize(stmt)

class angr.analyses.decompiler.peephole_optimizations.base.PeepholeOptimizationExprBase(project, kb, func_addr=None)

Bases: object

The base class for all peephole optimizations that are applied on AIL expressions.

Parameters:

• project (Project | None) –

• kb (KnowledgeBase | None) –

• func_addr (int | None) –

NAME = 'Peephole Optimization - Expression'

DESCRIPTION = 'Peephole Optimization - Expression'

expr_classes = None

__init__(project, kb, func_addr=None)

Parameters:

• project (Project | None) –

• kb (KnowledgeBase | None) –

• func_addr (int | None) –

project: Optional[Project]

kb: Optional[KnowledgeBase]

func_addr: Optional[int]

optimize(expr)

static is_bool_expr(ail_expr)

class angr.analyses.decompiler.region_identifier.RegionIdentifier(func, cond_proc=None, graph=None, largest_successor_tree_outside_loop=True, force_loop_single_exit=True, complete_successors=False)

Bases: Analysis

Identifies regions within a function.

__init__(func, cond_proc=None, graph=None, largest_successor_tree_outside_loop=True, force_loop_single_exit=True, complete_successors=False)

static slice_graph(graph, node, frontier, include_frontier=False)

Generate a slice of the graph from the head node to the given frontier.

Parameters:

• graph (networkx.DiGraph) – The graph to work on.

• node – The starting node in the graph.

• frontier – A list of frontier nodes.

• include_frontier (bool) – Whether the frontier nodes are included in the slice or not.

Returns:

A subgraph.

Return type:

networkx.DiGraph

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

class angr.analyses.decompiler.region_simplifiers.cascading_cond_transformer.CascadingConditionTransformer(node)

Bases: SequenceWalker

Identifies and transforms if { … } else { if { … } else { … } } to if { … } else if { … } else if { … }.

__init__(node)

walk(sequence)

class angr.analyses.decompiler.region_simplifiers.cascading_ifs.CascadingIfsRemover(node)

Bases: SequenceWalker

Coalesce cascading If constructs. Transforming the following construct:

if (cond_a) {
    if (cond_b) {
        true_body
    } else { }
} else { }

into:

if (cond_a and cond_b) {
    true_body
} else { }

__init__(node)

walk(sequence)

class angr.analyses.decompiler.region_simplifiers.expr_folding.LocationBase

Bases: object

class angr.analyses.decompiler.region_simplifiers.expr_folding.StatementLocation(block_addr, block_idx, stmt_idx)

Bases: LocationBase

__init__(block_addr, block_idx, stmt_idx)

block_addr

block_idx

stmt_idx

copy()

class angr.analyses.decompiler.region_simplifiers.expr_folding.ExpressionLocation(block_addr, block_idx, stmt_idx, expr_idx)

Bases: LocationBase

__init__(block_addr, block_idx, stmt_idx, expr_idx)

block_addr

block_idx

stmt_idx

expr_idx

statement_location()

Return type:

StatementLocation

class angr.analyses.decompiler.region_simplifiers.expr_folding.ConditionLocation(cond_node_addr, case_idx=None)

Bases: LocationBase

Parameters:

case_idx (int | None) –

__init__(cond_node_addr, case_idx=None)

Parameters:

case_idx (int | None) –

node_addr

case_idx

class angr.analyses.decompiler.region_simplifiers.expr_folding.ConditionalBreakLocation(node_addr)

Bases: LocationBase

__init__(node_addr)

node_addr

class angr.analyses.decompiler.region_simplifiers.expr_folding.ExpressionUseFinder

Bases: AILBlockWalker

Find where each variable is used.

Additionally, determine if the expression being walked has load expressions inside. Such expressions can only be safely folded if there are no Store statements between the expression defining location and its use sites. For example, we can only safely fold variable assignments that use Load() when there are no Store()s between the assignment and its use site. Otherwise, the loaded expression may get updated later by a Store() statement.

Here is a real AIL block:

v16 = ((int)v23->field_5) + 1 & 255;
v23->field_5 = ((char)(((int)v23->field_5) + 1 & 255));
v13 = printf("Recieved packet %d for connection with %d\n", v16, a0 & 255);

In this case, folding v16 into the last printf() expression would be incorrect, since v23->field_5 is updated by the second statement.

__init__()

uses: DefaultDict[SimVariable, Set[Tuple[Expression, Optional[ExpressionLocation]]]]

has_load

walk(block)

Parameters:

block (Block) –

walk_expression(expr, stmt_idx=None, stmt=None, block=None)

Parameters:

• expr (Expression) –

• stmt_idx (int | None) –

• stmt (int | None) –

• block (Block | None) –

walk_statement(stmt)

Parameters:

stmt (Statement) –

class angr.analyses.decompiler.region_simplifiers.expr_folding.ExpressionCounter(node, variable_manager)

Bases: SequenceWalker

Find all expressions that are assigned once and only used once.

__init__(node, variable_manager)

walk(sequence)

class angr.analyses.decompiler.region_simplifiers.expr_folding.ExpressionReplacer(assignments, uses, variable_manager)

Bases: AILBlockWalker

Parameters:

• assignments (Dict) –

• uses (Dict) –

__init__(assignments, uses, variable_manager)

Parameters:

• assignments (Dict) –

• uses (Dict) –

walk(block)

Parameters:

block (Block) –

walk_expression(expr, stmt_idx=None, stmt=None, block=None)

Parameters:

• expr (Expression) –

• stmt_idx (int | None) –

• stmt (int | None) –

• block (Block | None) –

walk_statement(stmt)

Parameters:

stmt (Statement) –

class angr.analyses.decompiler.region_simplifiers.expr_folding.ExpressionFolder(assignments, uses, node, variable_manager)

Bases: SequenceWalker

Parameters:

• assignments (Dict) –

• uses (Dict) –

__init__(assignments, uses, node, variable_manager)

Parameters:

• assignments (Dict) –

• uses (Dict) –

walk(sequence)

class angr.analyses.decompiler.region_simplifiers.expr_folding.StoreStatementFinder(node, intervals)

Bases: SequenceWalker

Determine if there are any Store statements between two given statements.

This class overrides _handle_Sequence() and _handle_MultiNode() to ensure they traverse nodes from top to bottom.

Parameters:

intervals (Iterable[Tuple[StatementLocation, LocationBase]]) –

__init__(node, intervals)

Parameters:

intervals (Iterable[Tuple[StatementLocation, LocationBase]]) –

has_store(start, end)

Return type:

bool

Parameters:

• start (StatementLocation) –

• end (StatementLocation) –

walk(sequence)

class angr.analyses.decompiler.region_simplifiers.goto.GotoSimplifier(node, function=None, kb=None)

Bases: SequenceWalker

Remove unnecessary Jump statements. This simplifier also has the side effect of detecting Gotos that can’t be reduced in the structuring and eventual decompilation output. Because of this, when this analysis is run, gotos in decompilation will be detected and stored in the kb.gotos. See the _handle_irreducible_goto function below.

TODO: Move the recording of Gotos outside this function

__init__(node, function=None, kb=None)

walk(sequence)

class angr.analyses.decompiler.region_simplifiers.if_.IfSimplifier(node)

Bases: SequenceWalker

Remove unnecessary jump or conditional jump statements if they jump to the successor right afterwards.

__init__(node)

walk(sequence)

class angr.analyses.decompiler.region_simplifiers.ifelse.IfElseFlattener(node, functions)

Bases: SequenceWalker

Remove unnecessary else branches and make the else node a direct successor of the previous If node if the If node always returns.

__init__(node, functions)

walk(sequence)

class angr.analyses.decompiler.region_simplifiers.loop.LoopSimplifier(node)

Bases: SequenceWalker

Simplifies loops.

__init__(node)

walk(sequence)

class angr.analyses.decompiler.region_simplifiers.node_address_finder.NodeAddressFinder(node)

Bases: SequenceWalker

Walk the entire node and collect all addresses of nodes.

__init__(node)

walk(sequence)

class angr.analyses.decompiler.region_simplifiers.region_simplifier.RegionSimplifier(func, region, variable_kb=None, simplify_switches=True)

Bases: Analysis

Simplifies a given region.

Parameters:

simplify_switches (bool) –

__init__(func, region, variable_kb=None, simplify_switches=True)

Parameters:

simplify_switches (bool) –

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

class angr.analyses.decompiler.region_simplifiers.switch_cluster_simplifier.CmpOp(value)

Bases: Enum

All supported comparison operators.

LT = 0

GT = 1

EQ = 2

NE = 3

class angr.analyses.decompiler.region_simplifiers.switch_cluster_simplifier.ConditionalRegion(variable, op, value, node, parent=None)

Bases: object

Describes a conditional region.

Parameters:

• op (CmpOp) –

• value (int) –

• node (ConditionNode | Block) –

__init__(variable, op, value, node, parent=None)

Parameters:

• op (CmpOp) –

• value (int) –

• node (ConditionNode | Block) –

variable

op

value

node

parent

class angr.analyses.decompiler.region_simplifiers.switch_cluster_simplifier.SwitchCaseRegion(variable, node, parent=None)

Bases: object

Describes an already-recovered switch region.

Parameters:

node (SwitchCaseNode) –

__init__(variable, node, parent=None)

Parameters:

node (SwitchCaseNode) –

variable

node

parent

class angr.analyses.decompiler.region_simplifiers.switch_cluster_simplifier.SwitchClusterFinder(node)

Bases: SequenceWalker

Find comparisons and switches in order to identify switch clusters.

__init__(node)

walk(sequence)

class angr.analyses.decompiler.region_simplifiers.switch_cluster_simplifier.SwitchClusterReplacer(region, to_replace, replace_with)

Bases: SequenceWalker

Replace an identified switch cluster with a newly created SwitchCase node.

__init__(region, to_replace, replace_with)

walk(sequence)

angr.analyses.decompiler.region_simplifiers.switch_cluster_simplifier.is_simple_jump_node(node, case_addrs, targets=None)

Return type:

bool

Parameters:

targets (Set[int] | None) –

angr.analyses.decompiler.region_simplifiers.switch_cluster_simplifier.filter_cond_regions(cond_regions, case_addrs)

Remove all conditional regions that cannot be merged into switch(es).

Return type:

List[ConditionalRegion]

Parameters:

• cond_regions (List[ConditionalRegion]) –

• case_addrs (Set[int]) –

angr.analyses.decompiler.region_simplifiers.switch_cluster_simplifier.update_switch_case_list(cases, old_case_id, new_case_id)

Update cases in-place. Make new_case_id directly jump to old_case_id.

Return type:

None

Parameters:

• cases (List[Tuple[int | Tuple[int, ...], SequenceNode]]) –

• old_case_id (int | Tuple[int, ...]) –

• new_case_id (int) –

angr.analyses.decompiler.region_simplifiers.switch_cluster_simplifier.simplify_switch_clusters(region, var2condnodes, var2switches)

Identify switch clusters and simplify each of them.

Parameters:

• region – The region to simplify.

• var2condnodes (Dict[Any, List[ConditionalRegion]]) – A dict that stores the mapping from (potential) switch variables to conditional regions.

• var2switches (Dict[Any, List[SwitchCaseRegion]]) – A dict that stores the mapping from switch variables to switch-case regions.

Returns:

None

class angr.analyses.decompiler.region_simplifiers.switch_expr_simplifier.SwitchExpressionSimplifier(node)

Bases: SequenceWalker

Identifies switch expressions that adds or minuses a constant, removes the constant from the switch expression, and adjust all case expressions accordingly.

__init__(node)

walk(sequence)

class angr.analyses.decompiler.region_walker.RegionWalker

Bases: object

A simple traverser class that walks GraphRegion instances.

__init__()

walk(region)

Parameters:

region (GraphRegion) –

walk_node(region, node)

class angr.analyses.decompiler.redundant_label_remover.RedundantLabelRemover(node, jump_targets)

Bases: object

Remove redundant labels.

This optimization pass contains two separate passes. The first pass (self._walker0) finds all redundant labels (e.g., two or more labels for the same location) and records the replacement label for redundant labels in self._new_jump_target. The second pass (self._walker1) removes all redundant labels that (a) are not referenced anywhere (determined by jump_targets), or (b) are deemed replaceable by the first pass.

Parameters:

jump_targets (Set[Tuple[int, int | None]]) –

__init__(node, jump_targets)

Parameters:

jump_targets (Set[Tuple[int, int | None]]) –

class angr.analyses.decompiler.sequence_walker.SequenceWalker(handlers=None, exception_on_unsupported=False, update_seqnode_in_place=True)

Bases: object

Walks a SequenceNode and all its nodes, recursively.

__init__(handlers=None, exception_on_unsupported=False, update_seqnode_in_place=True)

walk(sequence)

class angr.analyses.decompiler.structured_codegen.base.PositionMappingElement(start, length, obj)

Bases: object

__init__(start, length, obj)

start: int

length: int

obj

class angr.analyses.decompiler.structured_codegen.base.PositionMapping

Bases: object

DUPLICATION_CHECK = True

__init__()

items()

add_mapping(start_pos, length, obj)

get_node(pos)

Parameters:

pos (int) –

get_element(pos)

Return type:

Optional[PositionMappingElement]

Parameters:

pos (int) –

class angr.analyses.decompiler.structured_codegen.base.InstructionMappingElement(ins_addr, posmap_pos)

Bases: object

__init__(ins_addr, posmap_pos)

ins_addr: int

posmap_pos: int

class angr.analyses.decompiler.structured_codegen.base.InstructionMapping

Bases: object

__init__()

items()

add_mapping(ins_addr, posmap_pos)

get_nearest_pos(ins_addr)

Return type:

Optional[int]

Parameters:

ins_addr (int) –

class angr.analyses.decompiler.structured_codegen.base.BaseStructuredCodeGenerator(flavor=None)

Bases: object

__init__(flavor=None)

reapply_options(options)

regenerate_text()

Return type:

None

reload_variable_types()

Return type:

None

angr.analyses.decompiler.structured_codegen.c.unpack_typeref(ty)

angr.analyses.decompiler.structured_codegen.c.unpack_pointer(ty)

Return type:

Optional[SimType]

angr.analyses.decompiler.structured_codegen.c.unpack_array(ty)

Return type:

Optional[SimType]

angr.analyses.decompiler.structured_codegen.c.squash_array_reference(ty)

angr.analyses.decompiler.structured_codegen.c.qualifies_for_simple_cast(ty1, ty2)

angr.analyses.decompiler.structured_codegen.c.qualifies_for_implicit_cast(ty1, ty2)

angr.analyses.decompiler.structured_codegen.c.extract_terms(expr)

Return type:

Tuple[int, List[Tuple[int, CExpression]]]

Parameters:

expr (CExpression) –

angr.analyses.decompiler.structured_codegen.c.is_machine_word_size_type(type_, arch)

Return type:

bool

Parameters:

• type_ (SimType) –

• arch (Arch) –

angr.analyses.decompiler.structured_codegen.c.guess_value_type(value, project)

Return type:

Optional[SimType]

Parameters:

• value (int) –

• project (Project) –

class angr.analyses.decompiler.structured_codegen.c.CConstruct(codegen)

Bases: object

Represents a program construct in C. Acts as the base class for all other representation constructions.

__init__(codegen)

codegen: StructuredCodeGenerator

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

c_repr_chunks(indent=0, asexpr=False)

static indent_str(indent=0)

class angr.analyses.decompiler.structured_codegen.c.CFunction(addr, name, functy, arg_list, statements, variables_in_use, variable_manager, demangled_name=None, show_demangled_name=True, **kwargs)

Bases: CConstruct

Represents a function in C.

Parameters:

• functy (SimTypeFunction) –

• arg_list (List[CVariable]) –

__init__(addr, name, functy, arg_list, statements, variables_in_use, variable_manager, demangled_name=None, show_demangled_name=True, **kwargs)

Parameters:

• functy (SimTypeFunction) –

• arg_list (List[CVariable]) –

addr

name

functy

arg_list

statements

variables_in_use

variable_manager: VariableManagerInternal

demangled_name

unified_local_vars: Dict[SimVariable, Set[Tuple[CVariable, SimType]]]

show_demangled_name

get_unified_local_vars()

Return type:

Dict[SimVariable, Set[Tuple[CVariable, SimType]]]

variable_list_repr_chunks(indent=0)

c_repr_chunks(indent=0, asexpr=False)

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

codegen: StructuredCodeGenerator

static indent_str(indent=0)

class angr.analyses.decompiler.structured_codegen.c.CStatement(codegen)

Bases: CConstruct

Represents a statement in C.

Parameters:

codegen (StructuredCodeGenerator) –

__init__(codegen)

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

c_repr_chunks(indent=0, asexpr=False)

codegen: StructuredCodeGenerator

static indent_str(indent=0)

class angr.analyses.decompiler.structured_codegen.c.CExpression(collapsed=False, **kwargs)

Bases: CConstruct

Base class for C expressions.

__init__(collapsed=False, **kwargs)

collapsed

property type

set_type(v)

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

c_repr_chunks(indent=0, asexpr=False)

codegen: StructuredCodeGenerator

static indent_str(indent=0)

class angr.analyses.decompiler.structured_codegen.c.CStatements(statements, **kwargs)

Bases: CStatement

Represents a sequence of statements in C.

__init__(statements, **kwargs)

statements

c_repr_chunks(indent=0, asexpr=False)

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

codegen: StructuredCodeGenerator

static indent_str(indent=0)

class angr.analyses.decompiler.structured_codegen.c.CAILBlock(block, **kwargs)

Bases: CStatement

Represents a block of AIL statements.

__init__(block, **kwargs)

block

c_repr_chunks(indent=0, asexpr=False)

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

codegen: StructuredCodeGenerator

static indent_str(indent=0)

class angr.analyses.decompiler.structured_codegen.c.CLoop(codegen)

Bases: CStatement

Represents a loop in C.

Parameters:

codegen (StructuredCodeGenerator) –

__init__(codegen)

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

c_repr_chunks(indent=0, asexpr=False)

codegen: StructuredCodeGenerator

static indent_str(indent=0)

class angr.analyses.decompiler.structured_codegen.c.CWhileLoop(condition, body, tags=None, **kwargs)

Bases: CLoop

Represents a while loop in C.

__init__(condition, body, tags=None, **kwargs)

condition

body

tags

c_repr_chunks(indent=0, asexpr=False)

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

codegen: StructuredCodeGenerator

static indent_str(indent=0)

class angr.analyses.decompiler.structured_codegen.c.CDoWhileLoop(condition, body, tags=None, **kwargs)

Bases: CLoop

Represents a do-while loop in C.

__init__(condition, body, tags=None, **kwargs)

condition

body

tags

c_repr_chunks(indent=0, asexpr=False)

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

codegen: StructuredCodeGenerator

static indent_str(indent=0)

class angr.analyses.decompiler.structured_codegen.c.CForLoop(initializer, condition, iterator, body, tags=None, **kwargs)

Bases: CStatement

Represents a for-loop in C.

__init__(initializer, condition, iterator, body, tags=None, **kwargs)

initializer

condition

iterator

body

tags

c_repr_chunks(indent=0, asexpr=False)

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

codegen: StructuredCodeGenerator

static indent_str(indent=0)

class angr.analyses.decompiler.structured_codegen.c.CIfElse(condition_and_nodes, else_node=None, tags=None, **kwargs)

Bases: CStatement

Represents an if-else construct in C.

Parameters:

condition_and_nodes (List[Tuple[CExpression, CStatement | None]]) –

__init__(condition_and_nodes, else_node=None, tags=None, **kwargs)

Parameters:

condition_and_nodes (List[Tuple[CExpression, CStatement | None]]) –

condition_and_nodes

else_node

tags

c_repr_chunks(indent=0, asexpr=False)

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

codegen: StructuredCodeGenerator

static indent_str(indent=0)

class angr.analyses.decompiler.structured_codegen.c.CIfBreak(condition, tags=None, **kwargs)

Bases: CStatement

Represents an if-break statement in C.

__init__(condition, tags=None, **kwargs)

condition

tags

c_repr_chunks(indent=0, asexpr=False)

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

codegen: StructuredCodeGenerator

static indent_str(indent=0)

class angr.analyses.decompiler.structured_codegen.c.CBreak(tags=None, **kwargs)

Bases: CStatement

Represents a break statement in C.

__init__(tags=None, **kwargs)

tags

c_repr_chunks(indent=0, asexpr=False)

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

codegen: StructuredCodeGenerator

static indent_str(indent=0)

class angr.analyses.decompiler.structured_codegen.c.CContinue(tags=None, **kwargs)

Bases: CStatement

Represents a continue statement in C.

__init__(tags=None, **kwargs)

tags

c_repr_chunks(indent=0, asexpr=False)

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

codegen: StructuredCodeGenerator

static indent_str(indent=0)

class angr.analyses.decompiler.structured_codegen.c.CSwitchCase(switch, cases, default, tags=None, **kwargs)

Bases: CStatement

Represents a switch-case statement in C.

__init__(switch, cases, default, tags=None, **kwargs)

switch

cases: List[Tuple[Union[int, Tuple[int]], CStatements]]

default

tags

c_repr_chunks(indent=0, asexpr=False)

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

codegen: StructuredCodeGenerator

static indent_str(indent=0)

class angr.analyses.decompiler.structured_codegen.c.CAssignment(lhs, rhs, tags=None, **kwargs)

Bases: CStatement

a = b

__init__(lhs, rhs, tags=None, **kwargs)

lhs

rhs

tags

c_repr_chunks(indent=0, asexpr=False)

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

codegen: StructuredCodeGenerator

static indent_str(indent=0)

class angr.analyses.decompiler.structured_codegen.c.CFunctionCall(callee_target, callee_func, args, returning=True, ret_expr=None, tags=None, is_expr=False, show_demangled_name=True, **kwargs)

Bases: CStatement, CExpression

func(arg0, arg1)

Variables:

• callee_func (Function) – The function getting called.

• is_expr – True if the return value of the function is written to ret_expr; Essentially, ret_expr = call().

Parameters:

is_expr (bool) –

__init__(callee_target, callee_func, args, returning=True, ret_expr=None, tags=None, is_expr=False, show_demangled_name=True, **kwargs)

Parameters:

is_expr (bool) –

callee_target

callee_func: Optional[Function]

args

returning

ret_expr

tags

is_expr

show_demangled_name

property prototype: SimTypeFunction | None

property type

c_repr_chunks(indent=0, asexpr=False)

Parameters:

• indent – Number of whitespace indentation characters.

• asexpr (bool) – True if this call is used as an expression (which means we will skip the generation of semicolons and newlines at the end of the call).

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

codegen: StructuredCodeGenerator

collapsed

static indent_str(indent=0)

set_type(v)

class angr.analyses.decompiler.structured_codegen.c.CReturn(retval, tags=None, **kwargs)

Bases: CStatement

__init__(retval, tags=None, **kwargs)

retval

tags

c_repr_chunks(indent=0, asexpr=False)

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

codegen: StructuredCodeGenerator

static indent_str(indent=0)

class angr.analyses.decompiler.structured_codegen.c.CGoto(target, target_idx, tags=None, **kwargs)

Bases: CStatement

__init__(target, target_idx, tags=None, **kwargs)

target: Union[int, CExpression]

target_idx

tags

c_repr_chunks(indent=0, asexpr=False)

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

codegen: StructuredCodeGenerator

static indent_str(indent=0)

class angr.analyses.decompiler.structured_codegen.c.CUnsupportedStatement(stmt, **kwargs)

Bases: CStatement

A wrapper for unsupported AIL statement.

__init__(stmt, **kwargs)

stmt

c_repr_chunks(indent=0, asexpr=False)

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

codegen: StructuredCodeGenerator

static indent_str(indent=0)

class angr.analyses.decompiler.structured_codegen.c.CLabel(name, ins_addr, block_idx, tags=None, **kwargs)

Bases: CStatement

Represents a label in C code.

Parameters:

• name (str) –

• ins_addr (int) –

• block_idx (int | None) –

__init__(name, ins_addr, block_idx, tags=None, **kwargs)

Parameters:

• name (str) –

• ins_addr (int) –

• block_idx (int | None) –

name

ins_addr

block_idx

tags

c_repr_chunks(indent=0, asexpr=False)

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

codegen: StructuredCodeGenerator

static indent_str(indent=0)

class angr.analyses.decompiler.structured_codegen.c.CStructField(struct_type, offset, field, tags=None, **kwargs)

Bases: CExpression

Parameters:

struct_type (SimStruct) –

__init__(struct_type, offset, field, tags=None, **kwargs)

Parameters:

struct_type (SimStruct) –

struct_type

offset

field

tags

property type

c_repr_chunks(indent=0, asexpr=False)

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

codegen: StructuredCodeGenerator

collapsed

static indent_str(indent=0)

set_type(v)

class angr.analyses.decompiler.structured_codegen.c.CFakeVariable(name, ty, tags=None, **kwargs)

Bases: CExpression

An uninterpreted name to display in the decompilation output. Pretty much always represents an error?

Parameters:

• name (str) –

• ty (SimType) –

__init__(name, ty, tags=None, **kwargs)

Parameters:

• name (str) –

• ty (SimType) –

name

tags

property type

c_repr_chunks(indent=0, asexpr=False)

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

codegen: StructuredCodeGenerator

collapsed

static indent_str(indent=0)

set_type(v)

class angr.analyses.decompiler.structured_codegen.c.CVariable(variable, unified_variable=None, variable_type=None, tags=None, **kwargs)

Bases: CExpression

CVariable represents access to a variable with the specified type (variable_type).

variable must be a SimVariable.

Parameters:

variable (SimVariable) –

__init__(variable, unified_variable=None, variable_type=None, tags=None, **kwargs)

Parameters:

variable (SimVariable) –

variable: SimVariable

unified_variable: Optional[SimVariable]

variable_type: SimType

tags

property type

c_repr_chunks(indent=0, asexpr=False)

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

codegen: StructuredCodeGenerator

collapsed

static indent_str(indent=0)

set_type(v)

class angr.analyses.decompiler.structured_codegen.c.CIndexedVariable(variable, index, variable_type=None, tags=None, **kwargs)

Bases: CExpression

Represent a variable (an array) that is indexed.

Parameters:

• variable (CExpression) –

• index (CExpression) –

__init__(variable, index, variable_type=None, tags=None, **kwargs)

Parameters:

• variable (CExpression) –

• index (CExpression) –

property type

c_repr_chunks(indent=0, asexpr=False)

collapsed

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

codegen: StructuredCodeGenerator

static indent_str(indent=0)

set_type(v)

class angr.analyses.decompiler.structured_codegen.c.CVariableField(variable, field, var_is_ptr=False, tags=None, **kwargs)

Bases: CExpression

Represent a field of a variable.

Parameters:

• variable (CExpression) –

• field (CStructField) –

• var_is_ptr (bool) –

__init__(variable, field, var_is_ptr=False, tags=None, **kwargs)

Parameters:

• variable (CExpression) –

• field (CStructField) –

• var_is_ptr (bool) –

property type

c_repr_chunks(indent=0, asexpr=False)

collapsed

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

codegen: StructuredCodeGenerator

static indent_str(indent=0)

set_type(v)

class angr.analyses.decompiler.structured_codegen.c.CUnaryOp(op, operand, tags=None, **kwargs)

Bases: CExpression

Unary operations.

Parameters:

operand (CExpression) –

__init__(op, operand, tags=None, **kwargs)

Parameters:

operand (CExpression) –

op

operand

tags

property type

c_repr_chunks(indent=0, asexpr=False)

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

codegen: StructuredCodeGenerator

collapsed

static indent_str(indent=0)

set_type(v)

class angr.analyses.decompiler.structured_codegen.c.CBinaryOp(op, lhs, rhs, tags=None, **kwargs)

Bases: CExpression

Binary operations.

Parameters:

tags (dict | None) –

__init__(op, lhs, rhs, tags=None, **kwargs)

Parameters:

tags (dict | None) –

op

lhs

rhs

tags

common_type

static compute_common_type(op, lhs_ty, rhs_ty)

Return type:

SimType

Parameters:

• op (str) –

• lhs_ty (SimType) –

• rhs_ty (SimType) –

property type

property op_precedence

c_repr_chunks(indent=0, asexpr=False)

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

codegen: StructuredCodeGenerator

collapsed

static indent_str(indent=0)

set_type(v)

class angr.analyses.decompiler.structured_codegen.c.CTypeCast(src_type, dst_type, expr, tags=None, **kwargs)

Bases: CExpression

Parameters:

• src_type (SimType | None) –

• dst_type (SimType) –

• expr (CExpression) –

__init__(src_type, dst_type, expr, tags=None, **kwargs)

Parameters:

• src_type (SimType | None) –

• dst_type (SimType) –

• expr (CExpression) –

src_type

dst_type

expr

tags

property type

c_repr_chunks(indent=0, asexpr=False)

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

codegen: StructuredCodeGenerator

collapsed

static indent_str(indent=0)

set_type(v)

class angr.analyses.decompiler.structured_codegen.c.CConstant(value, type_, reference_values=None, tags=None, **kwargs)

Bases: CExpression

Parameters:

• type_ (SimType) –

• tags (Dict | None) –

__init__(value, type_, reference_values=None, tags=None, **kwargs)

Parameters:

• type_ (SimType) –

• tags (Dict | None) –

value

reference_values

tags

property fmt

property fmt_hex

property fmt_neg

property type

static str_to_c_str(_str)

c_repr_chunks(indent=0, asexpr=False)

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

codegen: StructuredCodeGenerator

collapsed

static indent_str(indent=0)

set_type(v)

class angr.analyses.decompiler.structured_codegen.c.CRegister(reg, tags=None, **kwargs)

Bases: CExpression

__init__(reg, tags=None, **kwargs)

reg

tags

property type

c_repr_chunks(indent=0, asexpr=False)

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

codegen: StructuredCodeGenerator

collapsed

static indent_str(indent=0)

set_type(v)

class angr.analyses.decompiler.structured_codegen.c.CITE(cond, iftrue, iffalse, tags=None, **kwargs)

Bases: CExpression

__init__(cond, iftrue, iffalse, tags=None, **kwargs)

cond

iftrue

iffalse

tags

property type

c_repr_chunks(indent=0, asexpr=False)

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

codegen: StructuredCodeGenerator

collapsed

static indent_str(indent=0)

set_type(v)

class angr.analyses.decompiler.structured_codegen.c.CMultiStatementExpression(stmts, expr, tags=None, **kwargs)

Bases: CExpression

(stmt0, stmt1, stmt2, expr)

Parameters:

• stmts (CStatements) –

• expr (CExpression) –

__init__(stmts, expr, tags=None, **kwargs)

Parameters:

• stmts (CStatements) –

• expr (CExpression) –

stmts

expr

tags

property type

c_repr_chunks(indent=0, asexpr=False)

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

codegen: StructuredCodeGenerator

collapsed

static indent_str(indent=0)

set_type(v)

class angr.analyses.decompiler.structured_codegen.c.CDirtyExpression(dirty, **kwargs)

Bases: CExpression

Ideally all dirty expressions should be handled and converted to proper conversions during conversion from VEX to AIL. Eventually this class should not be used at all.

__init__(dirty, **kwargs)

dirty

property type

c_repr_chunks(indent=0, asexpr=False)

c_repr(indent=0, pos_to_node=None, pos_to_addr=None, addr_to_pos=None)

Creates the C representation of the code and displays it by constructing a large string. This function is called by each program function that needs to be decompiled. The map_pos_to_node and map_pos_to_addr act as position maps for the location of each variable and statement to be tracked for later GUI operations. The map_pos_to_addr also contains expressions that are nested inside of statements.

codegen: StructuredCodeGenerator

collapsed

static indent_str(indent=0)

set_type(v)

class angr.analyses.decompiler.structured_codegen.c.CClosingObject(opening_symbol)

Bases: object

A class to represent all objects that can be closed by it’s correspodning character. Examples: (), {}, []

__init__(opening_symbol)

opening_symbol

class angr.analyses.decompiler.structured_codegen.c.CStructuredCodeGenerator(func, sequence, indent=0, cfg=None, variable_kb=None, func_args=None, binop_depth_cutoff=16, show_casts=True, braces_on_own_lines=True, use_compound_assignments=True, show_local_types=True, comment_gotos=False, flavor=None, stmt_comments=None, expr_comments=None, show_externs=True, externs=None, const_formats=None, show_demangled_name=True)

Bases: BaseStructuredCodeGenerator, Analysis

Parameters:

• func_args (List[SimVariable] | None) –

• binop_depth_cutoff (int) –

__init__(func, sequence, indent=0, cfg=None, variable_kb=None, func_args=None, binop_depth_cutoff=16, show_casts=True, braces_on_own_lines=True, use_compound_assignments=True, show_local_types=True, comment_gotos=False, flavor=None, stmt_comments=None, expr_comments=None, show_externs=True, externs=None, const_formats=None, show_demangled_name=True)

Parameters:

• func_args (List[SimVariable] | None) –

• binop_depth_cutoff (int) –

reapply_options(options)

cleanup()

Remove existing rendering results.

regenerate_text()

Re-render text and re-generate all sorts of mapping information.

Return type:

None

RENDER_TYPE

alias of Tuple[str, PositionMapping, PositionMapping, InstructionMapping, Dict[Any, Set[Any]]]

render_text(cfunc)

Return type:

Tuple[str, PositionMapping, PositionMapping, InstructionMapping, Dict[Any, Set[Any]]]

Parameters:

cfunc (CFunction) –

reload_variable_types()

Return type:

None

default_simtype_from_size(n, signed=True)

Return type:

SimType

Parameters:

• n (int) –

• signed (bool) –

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

class angr.analyses.decompiler.structured_codegen.c.CStructuredCodeWalker

Bases: object

classmethod handle(obj)

classmethod handle_default(obj)

classmethod handle_CFunction(obj)

classmethod handle_CStatements(obj)

classmethod handle_CWhileLoop(obj)

classmethod handle_CDoWhileLoop(obj)

classmethod handle_CForLoop(obj)

classmethod handle_CIfElse(obj)

classmethod handle_CIfBreak(obj)

classmethod handle_CSwitchCase(obj)

classmethod handle_CAssignment(obj)

classmethod handle_CFunctionCall(obj)

classmethod handle_CReturn(obj)

classmethod handle_CGoto(obj)

classmethod handle_CIndexedVariable(obj)

classmethod handle_CVariableField(obj)

classmethod handle_CUnaryOp(obj)

classmethod handle_CBinaryOp(obj)

classmethod handle_CTypeCast(obj)

classmethod handle_CITE(obj)

class angr.analyses.decompiler.structured_codegen.c.MakeTypecastsImplicit

Bases: CStructuredCodeWalker

classmethod collapse(dst_ty, child)

Return type:

CExpression

Parameters:

• dst_ty (SimType) –

• child (CExpression) –

classmethod handle_CAssignment(obj)

classmethod handle_CFunctionCall(obj)

Parameters:

obj (CFunctionCall) –

classmethod handle_CReturn(obj)

Parameters:

obj (CReturn) –

classmethod handle_CBinaryOp(obj)

Parameters:

obj (CBinaryOp) –

classmethod handle(obj)

classmethod handle_CDoWhileLoop(obj)

classmethod handle_CForLoop(obj)

classmethod handle_CFunction(obj)

classmethod handle_CGoto(obj)

classmethod handle_CITE(obj)

classmethod handle_CIfBreak(obj)

classmethod handle_CIfElse(obj)

classmethod handle_CIndexedVariable(obj)

classmethod handle_CStatements(obj)

classmethod handle_CSwitchCase(obj)

classmethod handle_CTypeCast(obj)

Parameters:

obj (CTypeCast) –

classmethod handle_CUnaryOp(obj)

classmethod handle_CVariableField(obj)

classmethod handle_CWhileLoop(obj)

classmethod handle_default(obj)

class angr.analyses.decompiler.structured_codegen.c.FieldReferenceCleanup

Bases: CStructuredCodeWalker

classmethod handle(obj)

classmethod handle_CAssignment(obj)

classmethod handle_CBinaryOp(obj)

classmethod handle_CDoWhileLoop(obj)

classmethod handle_CForLoop(obj)

classmethod handle_CFunction(obj)

classmethod handle_CFunctionCall(obj)

classmethod handle_CGoto(obj)

classmethod handle_CITE(obj)

classmethod handle_CIfBreak(obj)

classmethod handle_CIfElse(obj)

classmethod handle_CIndexedVariable(obj)

classmethod handle_CReturn(obj)

classmethod handle_CStatements(obj)

classmethod handle_CSwitchCase(obj)

classmethod handle_CUnaryOp(obj)

classmethod handle_CVariableField(obj)

classmethod handle_CWhileLoop(obj)

classmethod handle_default(obj)

classmethod handle_CTypeCast(obj)

class angr.analyses.decompiler.structured_codegen.c.PointerArithmeticFixer

Bases: CStructuredCodeWalker

classmethod handle(obj)

classmethod handle_CAssignment(obj)

classmethod handle_CDoWhileLoop(obj)

classmethod handle_CForLoop(obj)

classmethod handle_CFunction(obj)

classmethod handle_CFunctionCall(obj)

classmethod handle_CGoto(obj)

classmethod handle_CITE(obj)

classmethod handle_CIfBreak(obj)

classmethod handle_CIfElse(obj)

classmethod handle_CIndexedVariable(obj)

classmethod handle_CReturn(obj)

classmethod handle_CStatements(obj)

classmethod handle_CSwitchCase(obj)

classmethod handle_CTypeCast(obj)

classmethod handle_CUnaryOp(obj)

classmethod handle_CVariableField(obj)

classmethod handle_CWhileLoop(obj)

classmethod handle_default(obj)

classmethod handle_CBinaryOp(obj)

angr.analyses.decompiler.structured_codegen.c.StructuredCodeGenerator

alias of CStructuredCodeGenerator

class angr.analyses.decompiler.structured_codegen.dwarf_import.ImportedLine(addr)

Bases: object

__init__(addr)

class angr.analyses.decompiler.structured_codegen.dwarf_import.ImportSourceCode(function, flavor='source', source_root=None, encoding='utf-8')

Bases: BaseStructuredCodeGenerator, Analysis

__init__(function, flavor='source', source_root=None, encoding='utf-8')

regenerate_text()

errors = []

named_errors = {}

reapply_options(options)

reload_variable_types()

Return type:

None

project: Project

kb: KnowledgeBase

class angr.analyses.decompiler.structured_codegen.dummy.DummyStructuredCodeGenerator(flavor, expr_comments=None, stmt_comments=None, configuration=None, const_formats=None)

Bases: BaseStructuredCodeGenerator

A dummy structured code generator that only stores user-specified information.

Parameters:

flavor (str) –

__init__(flavor, expr_comments=None, stmt_comments=None, configuration=None, const_formats=None)

Parameters:

flavor (str) –

reapply_options(options)

regenerate_text()

Return type:

None

reload_variable_types()

Return type:

None

angr.analyses.decompiler.utils.remove_last_statement(node)

angr.analyses.decompiler.utils.append_statement(node, stmt)

angr.analyses.decompiler.utils.replace_last_statement(node, old_stmt, new_stmt)

angr.analyses.decompiler.utils.extract_jump_targets(stmt)

Extract concrete goto targets from a Jump or a ConditionalJump statement.

Parameters:

stmt – The statement to analyze.

Returns:

A list of known concrete jump targets.

Return type:

list

angr.analyses.decompiler.utils.switch_extract_cmp_bounds(last_stmt)

Check the last statement of the switch-case header node, and extract lower+upper bounds for the comparison.

Parameters:

last_stmt (ConditionalJump) – The last statement of the switch-case header node.

Return type:

Optional[Tuple[Any, int, int]]

Returns:

A tuple of (comparison expression, lower bound, upper bound), or None

angr.analyses.decompiler.utils.get_ast_subexprs(claripy_ast)

angr.analyses.decompiler.utils.insert_node(parent, insert_location, node, node_idx, label=None)

Parameters:

• insert_location (str) –

• node_idx (int | Tuple[int] | None) –

angr.analyses.decompiler.utils.to_ail_supergraph(transition_graph)

Takes an AIL graph and converts it into a AIL graph that treats calls and redundant jumps as parts of a bigger block instead of transitions. Calls to returning functions do not terminate basic blocks.

Based on region_identifier super_graph

Return type:

DiGraph

Returns:

A converted super transition graph

Parameters:

transition_graph (DiGraph) –

angr.analyses.decompiler.utils.is_empty_node(node)

Return type:

bool

angr.analyses.decompiler.utils.is_empty_or_label_only_node(node)

Return type:

bool

angr.analyses.decompiler.utils.has_nonlabel_statements(block)

Return type:

bool

Parameters:

block (Block) –

angr.analyses.decompiler.utils.first_nonlabel_statement(block)

Return type:

Optional[Statement]

Parameters:

block (Block) –

angr.analyses.decompiler.utils.last_nonlabel_statement(block)

Return type:

Optional[Statement]

Parameters:

block (Block) –

angr.analyses.decompiler.utils.first_nonlabel_node(seq)

Return type:

Union[BaseNode, Block, None]

Parameters:

seq (SequenceNode) –

angr.analyses.decompiler.utils.remove_labels(graph)

Parameters:

graph (DiGraph) –

class angr.analyses.ddg.AST(op, *operands)

Bases: object

A mini implementation for AST

__init__(op, *operands)

class angr.analyses.ddg.ProgramVariable(variable, location, initial=False, arch=None)

Bases: object

Describes a variable in the program at a specific location.

Variables:

• variable (SimVariable) – The variable.

• location (CodeLocation) – Location of the variable.

__init__(variable, location, initial=False, arch=None)

property short_repr

class angr.analyses.ddg.DDGJob(cfg_node, call_depth)

Bases: object

__init__(cfg_node, call_depth)

class angr.analyses.ddg.LiveDefinitions

Bases: object

A collection of live definitions with some handy interfaces for definition killing and lookups.

__init__()

Constructor.

branch()

Create a branch of the current live definition collection.

Returns:

A new LiveDefinition instance.

Return type:

angr.analyses.ddg.LiveDefinitions

copy()

Make a hard copy of self.

Returns:

A new LiveDefinition instance.

Return type:

angr.analyses.ddg.LiveDefinitions

add_def(variable, location, size_threshold=32)

Add a new definition of variable.

Parameters:

• variable (SimVariable) – The variable being defined.

• location (CodeLocation) – Location of the varaible being defined.

• size_threshold (int) – The maximum bytes to consider for the variable.

Returns:

True if the definition was new, False otherwise

Return type:

bool

add_defs(variable, locations, size_threshold=32)

Add a collection of new definitions of a variable.

Parameters:

• variable (SimVariable) – The variable being defined.

• locations (iterable) – A collection of locations where the variable was defined.

• size_threshold (int) – The maximum bytes to consider for the variable.

Returns:

True if any of the definition was new, False otherwise

Return type:

bool

kill_def(variable, location, size_threshold=32)

Add a new definition for variable and kill all previous definitions.

Parameters:

• variable (SimVariable) – The variable to kill.

• location (CodeLocation) – The location where this variable is defined.

• size_threshold (int) – The maximum bytes to consider for the variable.

Returns:

None

lookup_defs(variable, size_threshold=32)

Find all definitions of the variable.

Parameters:

• variable (SimVariable) – The variable to lookup for.

• size_threshold (int) – The maximum bytes to consider for the variable. For example, if the variable is 100 byte long, only the first size_threshold bytes are considered.

Returns:

A set of code locations where the variable is defined.

Return type:

set

items()

An iterator that returns all live definitions.

Returns:

The iterator.

Return type:

iter

itervariables()

An iterator that returns all live variables.

Returns:

The iterator.

Return type:

iter

class angr.analyses.ddg.DDGViewItem(ddg, variable, simplified=False)

Bases: object

__init__(ddg, variable, simplified=False)

property depends_on

property dependents

class angr.analyses.ddg.DDGViewInstruction(cfg, ddg, insn_addr, simplified=False)

Bases: object

__init__(cfg, ddg, insn_addr, simplified=False)

property definitions: List[DDGViewItem]

Get all definitions located at the current instruction address.

Returns:

A list of ProgramVariable instances.

class angr.analyses.ddg.DDGView(cfg, ddg, simplified=False)

Bases: object

A view of the data dependence graph.

__init__(cfg, ddg, simplified=False)

class angr.analyses.ddg.DDG(cfg, start=None, call_depth=None, block_addrs=None)

Bases: Analysis

This is a fast data dependence graph directly generated from our CFG analysis result. The only reason for its existence is the speed. There is zero guarantee for being sound or accurate. You are supposed to use it only when you want to track the simplest data dependence, and you do not care about soundness or accuracy.

For a better data dependence graph, please consider performing a better static analysis first (like Value-set Analysis), and then construct a dependence graph on top of the analysis result (for example, the VFG in angr).

The DDG is based on a CFG, which should ideally be a CFGEmulated generated with the following options:

• keep_state=True to keep all input states

• state_add_options=angr.options.refs to store memory, register, and temporary value accesses

You may want to consider a high value for context_sensitivity_level as well when generating the CFG.

Also note that since we are using states from CFG, any improvement in analysis performed on CFG (like a points-to analysis) will directly benefit the DDG.

__init__(cfg, start=None, call_depth=None, block_addrs=None)

Parameters:

• cfg – Control flow graph. Please make sure each node has an associated state with it, e.g. by passing the keep_state=True and state_add_options=angr.options.refs arguments to CFGEmulated.

• start – An address, Specifies where we start the generation of this data dependence graph.

• call_depth – None or integers. A non-negative integer specifies how deep we would like to track in the call tree. None disables call_depth limit.

• block_addrs (iterable or None) – A collection of block addresses that the DDG analysis should be performed on.

property graph

A networkx DiGraph instance representing the dependence relations between statements. :rtype: networkx.DiGraph

Type:

returns

property data_graph

Get the data dependence graph.

Returns:

A networkx DiGraph instance representing data dependence.

Return type:

networkx.DiGraph

property simplified_data_graph

return:

property ast_graph

pp()

Pretty printing.

dbg_repr()

Representation for debugging.

get_predecessors(code_location)

Returns all predecessors of the code location.

Parameters:

code_location – A CodeLocation instance.

Returns:

A list of all predecessors.

function_dependency_graph(func)

Get a dependency graph for the function func.

Parameters:

func – The Function object in CFG.function_manager.

Returns:

A networkx.DiGraph instance.

data_sub_graph(pv, simplified=True, killing_edges=False, excluding_types=None)

Get a subgraph from the data graph or the simplified data graph that starts from node pv.

Parameters:

• pv (ProgramVariable) – The starting point of the subgraph.

• simplified (bool) – When True, the simplified data graph is used, otherwise the data graph is used.

• killing_edges (bool) – Are killing edges included or not.

• excluding_types (iterable) – Excluding edges whose types are among those excluded types.

Returns:

A subgraph.

Return type:

networkx.MultiDiGraph

find_definitions(variable, location=None, simplified_graph=True)

Find all definitions of the given variable.

Parameters:

• variable (SimVariable) –

• simplified_graph (bool) – True if you just want to search in the simplified graph instead of the normal graph. Usually the simplified graph suffices for finding definitions of register or memory variables.

Returns:

A collection of all variable definitions to the specific variable.

Return type:

list

find_consumers(var_def, simplified_graph=True)

Find all consumers to the specified variable definition.

Parameters:

• var_def (ProgramVariable) – The variable definition.

• simplified_graph (bool) – True if we want to search in the simplified graph, False otherwise.

Returns:

A collection of all consumers to the specified variable definition.

Return type:

list

find_killers(var_def, simplified_graph=True)

Find all killers to the specified variable definition.

Parameters:

• var_def (ProgramVariable) – The variable definition.

• simplified_graph (bool) – True if we want to search in the simplified graph, False otherwise.

Returns:

A collection of all killers to the specified variable definition.

Return type:

list

find_sources(var_def, simplified_graph=True)

Find all sources to the specified variable definition.

Parameters:

• var_def (ProgramVariable) – The variable definition.

• simplified_graph (bool) – True if we want to search in the simplified graph, False otherwise.

Returns:

A collection of all sources to the specified variable definition.

Return type:

list

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

class angr.analyses.flirt.FlirtAnalysis(sig=None)

Bases: Analysis

FlirtAnalysis accomplishes two purposes:

• If a FLIRT signature file is specified, it will match the given signature file against the current binary and rename recognized functions accordingly.

• If no FLIRT signature file is specified, it will use strings to determine possible libraries embedded in the current binary, and then match all possible signatures for the architecture.

Parameters:

sig (FlirtSignature | str | None) –

__init__(sig=None)

Parameters:

sig (FlirtSignature | str | None) –

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

class angr.engines.light.data.ArithmeticExpression(op, operands)

Bases: object

Add = 0

Sub = 1

Or = 2

And = 4

RShift = 8

LShift = 16

Mul = 32

Xor = 64

CONST_TYPES = (<class 'int'>, <class 'ailment.expression.Const'>)

__init__(op, operands)

op

operands

static try_unpack_const(expr)

class angr.engines.light.data.RegisterOffset(bits, reg, offset)

Bases: object

__init__(bits, reg, offset)

reg

offset

property bits

property symbolic

class angr.engines.light.data.SpOffset(bits, offset, is_base=False)

Bases: RegisterOffset

__init__(bits, offset, is_base=False)

is_base

property bits

offset

reg

property symbolic

class angr.engines.light.engine.SimEngineLightMixin(*args, logger=None, **kwargs)

Bases: object

A mixin base class for engines meant to perform static analysis

__init__(*args, logger=None, **kwargs)

static sp_offset(bits, offset)

Parameters:

• bits (int) –

• offset (int) –

static extract_offset_to_sp(spoffset_expr)

Extract the offset to the original stack pointer.

Parameters:

spoffset_expr (Base) – The claripy AST to parse.

Return type:

Optional[int]

Returns:

The offset to the original stack pointer, or None if spoffset_expr is not a supported type of SpOffset expression.

class angr.engines.light.engine.SimEngineLight

Bases: SimEngineLightMixin, SimEngine

A full-featured engine base class, suitable for static analysis

__init__()

process(state, *args, **kwargs)

The main entry point for an engine. Should take a state and return a result.

Parameters:

state – The state to proceed from

Returns:

The result. Whatever you want ;)

static extract_offset_to_sp(spoffset_expr)

Extract the offset to the original stack pointer.

Parameters:

spoffset_expr (Base) – The claripy AST to parse.

Return type:

Optional[int]

Returns:

The offset to the original stack pointer, or None if spoffset_expr is not a supported type of SpOffset expression.

static sp_offset(bits, offset)

Parameters:

• bits (int) –

• offset (int) –

class angr.engines.light.engine.SimEngineLightVEXMixin(*args, logger=None, **kwargs)

Bases: SimEngineLightMixin

A mixin for doing static analysis on VEX

__init__(*args, logger=None, **kwargs)

static extract_offset_to_sp(spoffset_expr)

Extract the offset to the original stack pointer.

Parameters:

spoffset_expr (Base) – The claripy AST to parse.

Return type:

Optional[int]

Returns:

The offset to the original stack pointer, or None if spoffset_expr is not a supported type of SpOffset expression.

static sp_offset(bits, offset)

Parameters:

• bits (int) –

• offset (int) –

class angr.engines.light.engine.SimEngineLightAILMixin(*args, logger=None, **kwargs)

Bases: SimEngineLightMixin

A mixin for doing static analysis on AIL

__init__(*args, logger=None, **kwargs)

static extract_offset_to_sp(spoffset_expr)

Extract the offset to the original stack pointer.

Parameters:

spoffset_expr (Base) – The claripy AST to parse.

Return type:

Optional[int]

Returns:

The offset to the original stack pointer, or None if spoffset_expr is not a supported type of SpOffset expression.

static sp_offset(bits, offset)

Parameters:

• bits (int) –

• offset (int) –

angr.engines.light.engine.SimEngineLightVEX

alias of SimEngineLightVEXMixin

angr.engines.light.engine.SimEngineLightAIL

alias of SimEngineLightAILMixin

class angr.analyses.propagator.values.Top(size)

Bases: object

__init__(size)

size

property bits

class angr.analyses.propagator.values.Bottom

Bases: object

class angr.analyses.propagator.vex_vars.VEXVariable

Bases: object

class angr.analyses.propagator.vex_vars.VEXMemVar(addr, size)

Bases: object

__init__(addr, size)

addr

size

class angr.analyses.propagator.vex_vars.VEXReg(offset, size)

Bases: VEXVariable

__init__(offset, size)

offset

size

class angr.analyses.propagator.vex_vars.VEXTmp(tmp)

Bases: VEXVariable

__init__(tmp)

tmp

class angr.analyses.propagator.engine_base.SimEnginePropagatorBase(stack_pointer_tracker=None, project=None, propagate_tmps=True, arch=None, reaching_definitions=None)

Bases: SimEngineLight

Parameters:

reaching_definitions (ReachingDefinitionsModel | None) –

__init__(stack_pointer_tracker=None, project=None, propagate_tmps=True, arch=None, reaching_definitions=None)

Parameters:

reaching_definitions (ReachingDefinitionsModel | None) –

process(state, *args, **kwargs)

The main entry point for an engine. Should take a state and return a result.

Parameters:

state – The state to proceed from

Returns:

The result. Whatever you want ;)

static extract_offset_to_sp(spoffset_expr)

Extract the offset to the original stack pointer.

Parameters:

spoffset_expr (Base) – The claripy AST to parse.

Return type:

Optional[int]

Returns:

The offset to the original stack pointer, or None if spoffset_expr is not a supported type of SpOffset expression.

static sp_offset(bits, offset)

Parameters:

• bits (int) –

• offset (int) –

class angr.analyses.propagator.engine_vex.SimEnginePropagatorVEX(stack_pointer_tracker=None, project=None, propagate_tmps=True, arch=None, reaching_definitions=None)

Bases: TopCheckerMixin, SimEngineLightVEXMixin, SimEnginePropagatorBase

Parameters:

reaching_definitions (ReachingDefinitionsModel | None) –

state: PropagatorVEXState

__init__(stack_pointer_tracker=None, project=None, propagate_tmps=True, arch=None, reaching_definitions=None)

Parameters:

reaching_definitions (ReachingDefinitionsModel | None) –

static extract_offset_to_sp(spoffset_expr)

Extract the offset to the original stack pointer.

Parameters:

spoffset_expr (Base) – The claripy AST to parse.

Return type:

Optional[int]

Returns:

The offset to the original stack pointer, or None if spoffset_expr is not a supported type of SpOffset expression.

process(state, *args, **kwargs)

The main entry point for an engine. Should take a state and return a result.

Parameters:

state – The state to proceed from

Returns:

The result. Whatever you want ;)

static sp_offset(bits, offset)

Parameters:

• bits (int) –

• offset (int) –

class angr.analyses.propagator.engine_ail.SimEnginePropagatorAIL(stack_pointer_tracker=None, project=None, propagate_tmps=True, arch=None, reaching_definitions=None)

Bases: SimEngineLightAILMixin, SimEnginePropagatorBase

The AIl engine for Propagator.

Parameters:

reaching_definitions (ReachingDefinitionsModel | None) –

state: PropagatorAILState

extract_offset_to_sp(expr)

Extract the offset to the original stack pointer.

Parameters:

• spoffset_expr – The claripy AST to parse.

• expr (Base | StackBaseOffset) –

Return type:

Optional[int]

Returns:

The offset to the original stack pointer, or None if spoffset_expr is not a supported type of SpOffset expression.

is_using_outdated_def(expr, expr_defat, current_loc, avoid=None)

Return type:

Tuple[bool, bool]

Parameters:

• expr (Expression) –

• expr_defat (CodeLocation | None) –

• current_loc (CodeLocation) –

• avoid (Expression | None) –

static has_tmpexpr(expr)

Return type:

bool

Parameters:

expr (Expression) –

__init__(stack_pointer_tracker=None, project=None, propagate_tmps=True, arch=None, reaching_definitions=None)

Parameters:

reaching_definitions (ReachingDefinitionsModel | None) –

process(state, *args, **kwargs)

The main entry point for an engine. Should take a state and return a result.

Parameters:

state – The state to proceed from

Returns:

The result. Whatever you want ;)

static sp_offset(bits, offset)

Parameters:

• bits (int) –

• offset (int) –

class angr.analyses.propagator.outdated_definition_walker.OutdatedDefinitionWalker(expr, expr_defat, livedefs_defat, current_loc, livedefs_currentloc, state, arch, avoid=None, extract_offset_to_sp=None)

Bases: AILBlockWalker

Walks an AIL expression to find outdated definitions.

Parameters:

• expr_defat (CodeLocation) –

• livedefs_defat (LiveDefinitions) –

• current_loc (CodeLocation) –

• livedefs_currentloc (LiveDefinitions) –

• state (PropagatorAILState) –

• arch (Arch) –

• avoid (Expression | None) –

• extract_offset_to_sp (Callable) –

__init__(expr, expr_defat, livedefs_defat, current_loc, livedefs_currentloc, state, arch, avoid=None, extract_offset_to_sp=None)

Parameters:

• expr_defat (CodeLocation) –

• livedefs_defat (LiveDefinitions) –

• current_loc (CodeLocation) –

• livedefs_currentloc (LiveDefinitions) –

• state (PropagatorAILState) –

• arch (Arch) –

• avoid (Expression | None) –

• extract_offset_to_sp (Callable | None) –

walk(block)

Parameters:

block (Block) –

walk_expression(expr, stmt_idx=None, stmt=None, block=None)

Parameters:

• expr (Expression) –

• stmt_idx (int | None) –

• stmt (int | None) –

• block (Block | None) –

walk_statement(stmt)

Parameters:

stmt (Statement) –

class angr.analyses.propagator.tmpvar_finder.TmpvarFinder(expr)

Bases: AILBlockWalkerBase

Walks an AIL expression to find Tmp expressions.

Parameters:

expr (Expression) –

__init__(expr)

Parameters:

expr (Expression) –

walk(block)

Parameters:

block (Block) –

walk_expression(expr, stmt_idx=None, stmt=None, block=None)

Parameters:

• expr (Expression) –

• stmt_idx (int | None) –

• stmt (int | None) –

• block (Block | None) –

walk_statement(stmt)

Parameters:

stmt (Statement) –

class angr.analyses.propagator.propagator.PropagatorAnalysis(func=None, block=None, func_graph=None, base_state=None, max_iterations=3, load_callback=None, stack_pointer_tracker=None, only_consts=False, completed_funcs=None, do_binops=True, store_tops=True, vex_cross_insn_opt=False, func_addr=None, gp=None, cache_results=False, key_prefix=None, reaching_definitions=None, profiling=False)

Bases: ForwardAnalysis, Analysis

PropagatorAnalysis implements copy propagation. It propagates values (either constant values or variables) and expressions inside a block or across a function.

PropagatorAnalysis supports both VEX and AIL. The VEX propagator only performs constant propagation. The AIL propagator performs both constant propagation and copy propagation of depth-N expressions.

PropagatorAnalysis performs certain arithmetic operations between constants, including but are not limited to:

• addition

• subtraction

• multiplication

• division

• xor

It also performs the following memory operations:

• Loading values from a known address

• Writing values to a stack variable

__init__(func=None, block=None, func_graph=None, base_state=None, max_iterations=3, load_callback=None, stack_pointer_tracker=None, only_consts=False, completed_funcs=None, do_binops=True, store_tops=True, vex_cross_insn_opt=False, func_addr=None, gp=None, cache_results=False, key_prefix=None, reaching_definitions=None, profiling=False)

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.

• func_addr (int | None) –

• gp (int | None) –

• cache_results (bool) –

• key_prefix (str | None) –

• reaching_definitions (ReachingDefinitionsModel | None) –

• profiling (bool) –

Returns:

None

property prop_key: Tuple[str | None, str, int, bool, bool, bool]

Gets a key that represents the function and the “flavor” of the propagation result.

property replacements

abort()

Abort the analysis :return: None

downsize()

errors = []

property graph: DiGraph

has_job(job)

Checks whether there exists another job which has the same job key. :type job: TypeVar(JobType) :param job: The job to check.

Return type:

bool

Returns:

True if there exists another job with the same key, False otherwise.

Parameters:

job (JobType) –

property jobs

named_errors = {}

property should_abort

Should the analysis be terminated. :return: True/False

project: Project

kb: KnowledgeBase

class angr.analyses.propagator.top_checker_mixin.TopCheckerMixin(*args, logger=None, **kwargs)

Bases: SimEngineLightMixin

__init__(*args, logger=None, **kwargs)

static extract_offset_to_sp(spoffset_expr)

Extract the offset to the original stack pointer.

Parameters:

spoffset_expr (Base) – The claripy AST to parse.

Return type:

Optional[int]

Returns:

The offset to the original stack pointer, or None if spoffset_expr is not a supported type of SpOffset expression.

static sp_offset(bits, offset)

Parameters:

• bits (int) –

• offset (int) –

class angr.analyses.reaching_definitions.LiveDefinitions(arch, track_tmps=False, canonical_size=8, register_definitions=None, stack_definitions=None, memory_definitions=None, heap_definitions=None, tmps=None, register_uses=None, stack_uses=None, heap_uses=None, memory_uses=None, tmp_uses=None)

Bases: object

A LiveDefinitions instance contains definitions and uses for register, stack, memory, and temporary variables, uncovered during the analysis.

Parameters:

• arch (Arch) –

• track_tmps (bool) –

• tmps (Dict[int, Set[Definition]]) –

• tmp_uses (Dict[int, Set[CodeLocation]]) –

INITIAL_SP_32BIT = 2147418112

INITIAL_SP_64BIT = 140737488289792

__init__(arch, track_tmps=False, canonical_size=8, register_definitions=None, stack_definitions=None, memory_definitions=None, heap_definitions=None, tmps=None, register_uses=None, stack_uses=None, heap_uses=None, memory_uses=None, tmp_uses=None)

Parameters:

• arch (Arch) –

• track_tmps (bool) –

project

arch

track_tmps

register_definitions

stack_definitions

memory_definitions

heap_definitions

tmps: Dict[int, Set[Definition]]

register_uses

stack_uses

heap_uses

memory_uses

tmp_uses: Dict[int, Set[CodeLocation]]

uses_by_codeloc: Dict[CodeLocation, Set[Definition]]

property registers: MultiValuedMemory

property stack: MultiValuedMemory

property memory: MultiValuedMemory

property heap: MultiValuedMemory

copy()

Return type:

LiveDefinitions

static top(bits)

Get a TOP value.

Parameters:

bits (int) – Width of the TOP value (in bits).

Returns:

The TOP value.

static is_top(expr)

Check if the given expression is a TOP value.

Parameters:

expr – The given expression.

Return type:

bool

Returns:

True if the expression is TOP, False otherwise.

stack_address(offset)

Return type:

Base

Parameters:

offset (int) –

static is_stack_address(addr)

Return type:

bool

Parameters:

addr (Base) –

static get_stack_offset(addr, had_stack_base=False)

Return type:

Optional[int]

Parameters:

addr (Base) –

static annotate_with_def(symvar, definition)

Parameters:

• symvar (Base) –

• definition (Definition) –

Returns:

static extract_defs(symvar)

Return type:

Generator[Definition, None, None]

Parameters:

symvar (Base) –

static extract_defs_from_mv(mv)

Return type:

Generator[Definition, None, None]

Parameters:

mv (MultiValues) –

get_sp()

Return the concrete value contained by the stack pointer.

Return type:

int

get_sp_offset()

Return the offset of the stack pointer.

Return type:

int

get_stack_address(offset)

Return type:

Optional[int]

Parameters:

offset (Base) –

stack_offset_to_stack_addr(offset)

Return type:

int

merge(*others)

Return type:

Tuple[LiveDefinitions, bool]

kill_definitions(atom)

Overwrite existing definitions w.r.t ‘atom’ with a dummy definition instance. A dummy definition will not be removed during simplification.

Parameters:

atom (Atom) –

Return type:

None

Returns:

None

kill_and_add_definition(atom, code_loc, data, dummy=False, tags=None, endness=None, annotated=False)

Return type:

Optional[MultiValues]

Parameters:

• atom (Atom) –

• code_loc (CodeLocation) –

• data (MultiValues) –

• tags (Set[Tag] | None) –

add_use(atom, code_loc, expr=None)

Return type:

None

Parameters:

• atom (Atom) –

• code_loc (CodeLocation) –

• expr (Any | None) –

add_use_by_def(definition, code_loc, expr=None)

Return type:

None

Parameters:

• definition (Definition) –

• code_loc (CodeLocation) –

• expr (Any | None) –

get_definitions(atom)

Return type:

Iterable[Definition]

Parameters:

atom (Atom) –

get_tmp_definitions(tmp_idx)

Return type:

Iterable[Definition]

Parameters:

tmp_idx (int) –

get_register_definitions(reg_offset, size, endness=None)

Return type:

Iterable[Definition]

Parameters:

• reg_offset (int) –

• size (int) –

get_stack_values(stack_offset, size, endness)

Return type:

Optional[MultiValues]

Parameters:

• stack_offset (int) –

• size (int) –

• endness (Endness) –

get_stack_definitions(stack_offset, size, endness)

Return type:

Iterable[Definition]

Parameters:

• stack_offset (int) –

• size (int) –

get_heap_definitions(heap_addr, size, endness)

Return type:

Iterable[Definition]

Parameters:

• heap_addr (int) –

• size (int) –

get_memory_definitions(addr, size, endness)

Return type:

Iterable[Definition]

Parameters:

• addr (int) –

• size (int) –

get_definitions_from_atoms(atoms)

Return type:

Iterable[Definition]

Parameters:

atoms (Iterable[Atom]) –

get_value_from_definition(definition)

Return type:

Optional[MultiValues]

Parameters:

definition (Definition) –

get_one_value_from_definition(definition)

Return type:

Optional[Base]

Parameters:

definition (Definition) –

get_concrete_value_from_definition(definition)

Return type:

Optional[int]

Parameters:

definition (Definition) –

get_value_from_atom(atom)

Return type:

Optional[MultiValues]

Parameters:

atom (Atom) –

get_one_value_from_atom(atom)

Return type:

Optional[Base]

Parameters:

atom (Atom) –

get_concrete_value_from_atom(atom)

Return type:

Optional[int]

Parameters:

atom (Atom) –

get_values(spec)

Return type:

Optional[MultiValues]

Parameters:

spec (Atom | Definition) –

get_one_value(spec)

Return type:

Optional[Base]

Parameters:

spec (Atom | Definition) –

get_concrete_value(spec)

Return type:

Optional[int]

Parameters:

spec (Atom | Definition) –

add_register_use(reg_offset, size, code_loc, expr=None)

Return type:

None

Parameters:

• reg_offset (int) –

• size (int) –

• code_loc (CodeLocation) –

• expr (Any | None) –

add_register_use_by_def(def_, code_loc, expr=None)

Return type:

None

Parameters:

• def_ (Definition) –

• code_loc (CodeLocation) –

• expr (Any | None) –

add_stack_use(atom, code_loc, expr=None)

Return type:

None

Parameters:

• atom (MemoryLocation) –

• code_loc (CodeLocation) –

• expr (Any | None) –

add_stack_use_by_def(def_, code_loc, expr=None)

Return type:

None

Parameters:

• def_ (Definition) –

• code_loc (CodeLocation) –

• expr (Any | None) –

add_heap_use(atom, code_loc, expr=None)

Return type:

None

Parameters:

• atom (MemoryLocation) –

• code_loc (CodeLocation) –

• expr (Any | None) –

add_heap_use_by_def(def_, code_loc, expr=None)

Return type:

None

Parameters:

• def_ (Definition) –

• code_loc (CodeLocation) –

• expr (Any | None) –

add_memory_use(atom, code_loc, expr=None)

Return type:

None

Parameters:

• atom (MemoryLocation) –

• code_loc (CodeLocation) –

• expr (Any | None) –

add_memory_use_by_def(def_, code_loc, expr=None)

Return type:

None

Parameters:

• def_ (Definition) –

• code_loc (CodeLocation) –

• expr (Any | None) –

add_tmp_use(atom, code_loc)

Return type:

None

Parameters:

• atom (Tmp) –

• code_loc (CodeLocation) –

add_tmp_use_by_def(def_, code_loc)

Return type:

None

Parameters:

• def_ (Definition) –

• code_loc (CodeLocation) –

class angr.analyses.reaching_definitions.ObservationPointType(value)

Bases: IntEnum

Enum to replace the previously generic constants This makes it possible to annotate where they are expected by typing something as ObservationPointType instead of Literal[0,1]

OP_BEFORE = 0

OP_AFTER = 1

class angr.analyses.reaching_definitions.AtomKind(value)

Bases: Enum

An enum indicating the class of an atom

REGISTER = 1

MEMORY = 2

TMP = 3

GUARD = 4

CONSTANT = 5

class angr.analyses.reaching_definitions.Atom(size)

Bases: object

This class represents a data storage location manipulated by IR instructions.

It could either be a Tmp (temporary variable), a Register, a MemoryLocation.

__init__(size)

Parameters:

size – The size of the atom in bytes

size

property bits: int

static from_ail_expr(expr, arch, full_reg=False)

Return type:

Register

Parameters:

• expr (Expression) –

• arch (Arch) –

• full_reg (bool) –

static from_argument(argument, arch, full_reg=False, sp=None)

Instanciate an Atom from a given argument.

Parameters:

• argument (SimFunctionArgument) – The argument to create a new atom from.

• registers – A mapping representing the registers of a given architecture.

• full_reg – Whether to return an atom indicating the entire register if the argument only specifies a slice of the register.

• sp (Optional[int]) – The current stack offset. Optional. Only used when argument is a SimStackArg.

• arch (Arch) –

Return type:

Union[Register, MemoryLocation]

static reg(thing, size=None, arch=None)

Create a Register atom.

Parameters:

• thing (Union[str, NewType()(RegisterOffset, int)]) – The register offset (e.g., project.arch.registers[“rax”][0]) or the register name (e.g., “rax”).

• size (Optional[int]) – Size of the register atom. Must be provided when creating the atom using a register offset.

• arch (Optional[Arch]) – The architecture. Must be provided when creating the atom using a register name.

Return type:

Register

Returns:

The Register Atom object.

static register(thing, size=None, arch=None)

Create a Register atom.

Parameters:

• thing (Union[str, NewType()(RegisterOffset, int)]) – The register offset (e.g., project.arch.registers[“rax”][0]) or the register name (e.g., “rax”).

• size (Optional[int]) – Size of the register atom. Must be provided when creating the atom using a register offset.

• arch (Optional[Arch]) – The architecture. Must be provided when creating the atom using a register name.

Return type:

Register

Returns:

The Register Atom object.

static mem(addr, size, endness=None)

Create a MemoryLocation atom,

Parameters:

• addr (Union[SpOffset, HeapAddress, int]) – The memory location. Can be an SpOffset for stack variables, an int for global memory variables, or a HeapAddress for items on the heap.

• size (int) – Size of the atom.

• endness (Optional[str]) – Optional, either “Iend_LE” or “Iend_BE”.

Return type:

MemoryLocation

Returns:

The MemoryLocation Atom object.

static memory(addr, size, endness=None)

Create a MemoryLocation atom,

Parameters:

• addr (Union[SpOffset, HeapAddress, int]) – The memory location. Can be an SpOffset for stack variables, an int for global memory variables, or a HeapAddress for items on the heap.

• size (int) – Size of the atom.

• endness (Optional[str]) – Optional, either “Iend_LE” or “Iend_BE”.

Return type:

MemoryLocation

Returns:

The MemoryLocation Atom object.

class angr.analyses.reaching_definitions.Register(reg_offset, size, arch=None)

Bases: Atom

Represents a given CPU register.

As an IR abstracts the CPU design to target different architectures, registers are represented as a separated memory space. Thus a register is defined by its offset from the base of this memory and its size.

Variables:

• reg_offset (int) – The offset from the base to define its place in the memory bloc.

• size (int) – The size, in number of bytes.

Parameters:

• reg_offset (RegisterOffset) –

• size (int) –

• arch (Arch | None) –

__init__(reg_offset, size, arch=None)

Parameters:

• size (int) – The size of the atom in bytes

• reg_offset (RegisterOffset) –

• arch (Arch | None) –

reg_offset

arch

property name: str

property bits: int

static from_ail_expr(expr, arch, full_reg=False)

Return type:

Register

Parameters:

• expr (Expression) –

• arch (Arch) –

• full_reg (bool) –

static from_argument(argument, arch, full_reg=False, sp=None)

Instanciate an Atom from a given argument.

Parameters:

• argument (SimFunctionArgument) – The argument to create a new atom from.

• registers – A mapping representing the registers of a given architecture.

• full_reg – Whether to return an atom indicating the entire register if the argument only specifies a slice of the register.

• sp (Optional[int]) – The current stack offset. Optional. Only used when argument is a SimStackArg.

• arch (Arch) –

Return type:

Union[Register, MemoryLocation]

static mem(addr, size, endness=None)

Create a MemoryLocation atom,

Parameters:

• addr (Union[SpOffset, HeapAddress, int]) – The memory location. Can be an SpOffset for stack variables, an int for global memory variables, or a HeapAddress for items on the heap.

• size (int) – Size of the atom.

• endness (Optional[str]) – Optional, either “Iend_LE” or “Iend_BE”.

Return type:

MemoryLocation

Returns:

The MemoryLocation Atom object.

static memory(addr, size, endness=None)

Create a MemoryLocation atom,

Parameters:

• addr (Union[SpOffset, HeapAddress, int]) – The memory location. Can be an SpOffset for stack variables, an int for global memory variables, or a HeapAddress for items on the heap.

• size (int) – Size of the atom.

• endness (Optional[str]) – Optional, either “Iend_LE” or “Iend_BE”.

Return type:

MemoryLocation

Returns:

The MemoryLocation Atom object.

static reg(thing, size=None, arch=None)

Create a Register atom.

Parameters:

• thing (Union[str, NewType()(RegisterOffset, int)]) – The register offset (e.g., project.arch.registers[“rax”][0]) or the register name (e.g., “rax”).

• size (Optional[int]) – Size of the register atom. Must be provided when creating the atom using a register offset.

• arch (Optional[Arch]) – The architecture. Must be provided when creating the atom using a register name.

Return type:

Register

Returns:

The Register Atom object.

static register(thing, size=None, arch=None)

Create a Register atom.

Parameters:

• thing (Union[str, NewType()(RegisterOffset, int)]) – The register offset (e.g., project.arch.registers[“rax”][0]) or the register name (e.g., “rax”).

• size (Optional[int]) – Size of the register atom. Must be provided when creating the atom using a register offset.

• arch (Optional[Arch]) – The architecture. Must be provided when creating the atom using a register name.

Return type:

Register

Returns:

The Register Atom object.

size

class angr.analyses.reaching_definitions.MemoryLocation(addr, size, endness=None)

Bases: Atom

Represents a memory slice.

It is characterized by its address and its size.

Parameters:

• addr (SpOffset | int | BV) –

• size (int) –

• endness (str | None) –

__init__(addr, size, endness=None)

Parameters:

• addr (int) – The address of the beginning memory location slice.

• size (int) – The size of the represented memory location, in bytes.

• endness (str | None) –

addr: Union[SpOffset, int, BV]

endness

property is_on_stack: bool

True if this memory location is located on the stack.

property symbolic: bool

property bits: int

static from_ail_expr(expr, arch, full_reg=False)

Return type:

Register

Parameters:

• expr (Expression) –

• arch (Arch) –

• full_reg (bool) –

static from_argument(argument, arch, full_reg=False, sp=None)

Instanciate an Atom from a given argument.

Parameters:

• argument (SimFunctionArgument) – The argument to create a new atom from.

• registers – A mapping representing the registers of a given architecture.

• full_reg – Whether to return an atom indicating the entire register if the argument only specifies a slice of the register.

• sp (Optional[int]) – The current stack offset. Optional. Only used when argument is a SimStackArg.

• arch (Arch) –

Return type:

Union[Register, MemoryLocation]

static mem(addr, size, endness=None)

Create a MemoryLocation atom,

Parameters:

• addr (Union[SpOffset, HeapAddress, int]) – The memory location. Can be an SpOffset for stack variables, an int for global memory variables, or a HeapAddress for items on the heap.

• size (int) – Size of the atom.

• endness (Optional[str]) – Optional, either “Iend_LE” or “Iend_BE”.

Return type:

MemoryLocation

Returns:

The MemoryLocation Atom object.

static memory(addr, size, endness=None)

Create a MemoryLocation atom,

Parameters:

• addr (Union[SpOffset, HeapAddress, int]) – The memory location. Can be an SpOffset for stack variables, an int for global memory variables, or a HeapAddress for items on the heap.

• size (int) – Size of the atom.

• endness (Optional[str]) – Optional, either “Iend_LE” or “Iend_BE”.

Return type:

MemoryLocation

Returns:

The MemoryLocation Atom object.

static reg(thing, size=None, arch=None)

Create a Register atom.

Parameters:

• thing (Union[str, NewType()(RegisterOffset, int)]) – The register offset (e.g., project.arch.registers[“rax”][0]) or the register name (e.g., “rax”).

• size (Optional[int]) – Size of the register atom. Must be provided when creating the atom using a register offset.

• arch (Optional[Arch]) – The architecture. Must be provided when creating the atom using a register name.

Return type:

Register

Returns:

The Register Atom object.

static register(thing, size=None, arch=None)

Create a Register atom.

Parameters:

• thing (Union[str, NewType()(RegisterOffset, int)]) – The register offset (e.g., project.arch.registers[“rax”][0]) or the register name (e.g., “rax”).

• size (Optional[int]) – Size of the register atom. Must be provided when creating the atom using a register offset.

• arch (Optional[Arch]) – The architecture. Must be provided when creating the atom using a register name.

Return type:

Register

Returns:

The Register Atom object.

size

class angr.analyses.reaching_definitions.Tmp(tmp_idx, size)

Bases: Atom

Represents a variable used by the IR to store intermediate values.

Parameters:

• tmp_idx (int) –

• size (int) –

__init__(tmp_idx, size)

Parameters:

• size (int) – The size of the atom in bytes

• tmp_idx (int) –

tmp_idx

property bits: int

static from_ail_expr(expr, arch, full_reg=False)

Return type:

Register

Parameters:

• expr (Expression) –

• arch (Arch) –

• full_reg (bool) –

static from_argument(argument, arch, full_reg=False, sp=None)

Instanciate an Atom from a given argument.

Parameters:

• argument (SimFunctionArgument) – The argument to create a new atom from.

• registers – A mapping representing the registers of a given architecture.

• full_reg – Whether to return an atom indicating the entire register if the argument only specifies a slice of the register.

• sp (Optional[int]) – The current stack offset. Optional. Only used when argument is a SimStackArg.

• arch (Arch) –

Return type:

Union[Register, MemoryLocation]

static mem(addr, size, endness=None)

Create a MemoryLocation atom,

Parameters:

• addr (Union[SpOffset, HeapAddress, int]) – The memory location. Can be an SpOffset for stack variables, an int for global memory variables, or a HeapAddress for items on the heap.

• size (int) – Size of the atom.

• endness (Optional[str]) – Optional, either “Iend_LE” or “Iend_BE”.

Return type:

MemoryLocation

Returns:

The MemoryLocation Atom object.

static memory(addr, size, endness=None)

Create a MemoryLocation atom,

Parameters:

• addr (Union[SpOffset, HeapAddress, int]) – The memory location. Can be an SpOffset for stack variables, an int for global memory variables, or a HeapAddress for items on the heap.

• size (int) – Size of the atom.

• endness (Optional[str]) – Optional, either “Iend_LE” or “Iend_BE”.

Return type:

MemoryLocation

Returns:

The MemoryLocation Atom object.

static reg(thing, size=None, arch=None)

Create a Register atom.

Parameters:

• thing (Union[str, NewType()(RegisterOffset, int)]) – The register offset (e.g., project.arch.registers[“rax”][0]) or the register name (e.g., “rax”).

• size (Optional[int]) – Size of the register atom. Must be provided when creating the atom using a register offset.

• arch (Optional[Arch]) – The architecture. Must be provided when creating the atom using a register name.

Return type:

Register

Returns:

The Register Atom object.

static register(thing, size=None, arch=None)

Create a Register atom.

Parameters:

• thing (Union[str, NewType()(RegisterOffset, int)]) – The register offset (e.g., project.arch.registers[“rax”][0]) or the register name (e.g., “rax”).

• size (Optional[int]) – Size of the register atom. Must be provided when creating the atom using a register offset.

• arch (Optional[Arch]) – The architecture. Must be provided when creating the atom using a register name.

Return type:

Register

Returns:

The Register Atom object.

size

class angr.analyses.reaching_definitions.GuardUse(target)

Bases: Atom

Implements a guard use.

__init__(target)

Parameters:

size – The size of the atom in bytes

target

property bits: int

static from_ail_expr(expr, arch, full_reg=False)

Return type:

Register

Parameters:

• expr (Expression) –

• arch (Arch) –

• full_reg (bool) –

static from_argument(argument, arch, full_reg=False, sp=None)

Instanciate an Atom from a given argument.

Parameters:

• argument (SimFunctionArgument) – The argument to create a new atom from.

• registers – A mapping representing the registers of a given architecture.

• full_reg – Whether to return an atom indicating the entire register if the argument only specifies a slice of the register.

• sp (Optional[int]) – The current stack offset. Optional. Only used when argument is a SimStackArg.

• arch (Arch) –

Return type:

Union[Register, MemoryLocation]

static mem(addr, size, endness=None)

Create a MemoryLocation atom,

Parameters:

• addr (Union[SpOffset, HeapAddress, int]) – The memory location. Can be an SpOffset for stack variables, an int for global memory variables, or a HeapAddress for items on the heap.

• size (int) – Size of the atom.

• endness (Optional[str]) – Optional, either “Iend_LE” or “Iend_BE”.

Return type:

MemoryLocation

Returns:

The MemoryLocation Atom object.

static memory(addr, size, endness=None)

Create a MemoryLocation atom,

Parameters:

• addr (Union[SpOffset, HeapAddress, int]) – The memory location. Can be an SpOffset for stack variables, an int for global memory variables, or a HeapAddress for items on the heap.

• size (int) – Size of the atom.

• endness (Optional[str]) – Optional, either “Iend_LE” or “Iend_BE”.

Return type:

MemoryLocation

Returns:

The MemoryLocation Atom object.

static reg(thing, size=None, arch=None)

Create a Register atom.

Parameters:

• thing (Union[str, NewType()(RegisterOffset, int)]) – The register offset (e.g., project.arch.registers[“rax”][0]) or the register name (e.g., “rax”).

• size (Optional[int]) – Size of the register atom. Must be provided when creating the atom using a register offset.

• arch (Optional[Arch]) – The architecture. Must be provided when creating the atom using a register name.

Return type:

Register

Returns:

The Register Atom object.

static register(thing, size=None, arch=None)

Create a Register atom.

Parameters:

• thing (Union[str, NewType()(RegisterOffset, int)]) – The register offset (e.g., project.arch.registers[“rax”][0]) or the register name (e.g., “rax”).

• size (Optional[int]) – Size of the register atom. Must be provided when creating the atom using a register offset.

• arch (Optional[Arch]) – The architecture. Must be provided when creating the atom using a register name.

Return type:

Register

Returns:

The Register Atom object.

size

class angr.analyses.reaching_definitions.ConstantSrc(value, size)

Bases: Atom

Represents a constant.

Parameters:

• value (int) –

• size (int) –

__init__(value, size)

Parameters:

• size (int) – The size of the atom in bytes

• value (int) –

value: int

property bits: int

static from_ail_expr(expr, arch, full_reg=False)

Return type:

Register

Parameters:

• expr (Expression) –

• arch (Arch) –

• full_reg (bool) –

static from_argument(argument, arch, full_reg=False, sp=None)

Instanciate an Atom from a given argument.

Parameters:

• argument (SimFunctionArgument) – The argument to create a new atom from.

• registers – A mapping representing the registers of a given architecture.

• full_reg – Whether to return an atom indicating the entire register if the argument only specifies a slice of the register.

• sp (Optional[int]) – The current stack offset. Optional. Only used when argument is a SimStackArg.

• arch (Arch) –

Return type:

Union[Register, MemoryLocation]

static mem(addr, size, endness=None)

Create a MemoryLocation atom,

Parameters:

• addr (Union[SpOffset, HeapAddress, int]) – The memory location. Can be an SpOffset for stack variables, an int for global memory variables, or a HeapAddress for items on the heap.

• size (int) – Size of the atom.

• endness (Optional[str]) – Optional, either “Iend_LE” or “Iend_BE”.

Return type:

MemoryLocation

Returns:

The MemoryLocation Atom object.

static memory(addr, size, endness=None)

Create a MemoryLocation atom,

Parameters:

• addr (Union[SpOffset, HeapAddress, int]) – The memory location. Can be an SpOffset for stack variables, an int for global memory variables, or a HeapAddress for items on the heap.

• size (int) – Size of the atom.

• endness (Optional[str]) – Optional, either “Iend_LE” or “Iend_BE”.

Return type:

MemoryLocation

Returns:

The MemoryLocation Atom object.

static reg(thing, size=None, arch=None)

Create a Register atom.

Parameters:

• thing (Union[str, NewType()(RegisterOffset, int)]) – The register offset (e.g., project.arch.registers[“rax”][0]) or the register name (e.g., “rax”).

• size (Optional[int]) – Size of the register atom. Must be provided when creating the atom using a register offset.

• arch (Optional[Arch]) – The architecture. Must be provided when creating the atom using a register name.

Return type:

Register

Returns:

The Register Atom object.

static register(thing, size=None, arch=None)

Create a Register atom.

Parameters:

• thing (Union[str, NewType()(RegisterOffset, int)]) – The register offset (e.g., project.arch.registers[“rax”][0]) or the register name (e.g., “rax”).

• size (Optional[int]) – Size of the register atom. Must be provided when creating the atom using a register offset.

• arch (Optional[Arch]) – The architecture. Must be provided when creating the atom using a register name.

Return type:

Register

Returns:

The Register Atom object.

size

class angr.analyses.reaching_definitions.Definition(atom, codeloc, dummy=False, tags=None)

Bases: Generic[A]

An atom definition.

Variables:

• atom – The atom being defined.

• codeloc – Where this definition is created in the original binary code.

• dummy – Tell whether the definition should be considered dummy or not. During simplification by AILment, definitions marked as dummy will not be removed.

• tags – A set of tags containing information about the definition gathered during analyses.

__init__(atom, codeloc, dummy=False, tags=None)

Parameters:

• atom (A) –

• codeloc (CodeLocation) –

• dummy (bool) –

• tags (Set[Tag] | None) –

atom: TypeVar(A, bound= Atom)

codeloc: CodeLocation

dummy: bool

tags

property offset: int

property size: int

matches(**kwargs)

Return whether this definition has certain characteristics.

Return type:

bool

class angr.analyses.reaching_definitions.ReachingDefinitionsAnalysis(subject=None, func_graph=None, max_iterations=3, track_tmps=False, track_consts=True, observation_points=None, init_state=None, init_context=None, cc=None, function_handler=None, observe_all=False, visited_blocks=None, dep_graph=True, observe_callback=None, canonical_size=8, stack_pointer_tracker=None)

Bases: ForwardAnalysis[ReachingDefinitionsState, NodeType, object, object], Analysis

ReachingDefinitionsAnalysis is a text-book implementation of a static data-flow analysis that works on either a function or a block. It supports both VEX and AIL. By registering observers to observation points, users may use this analysis to generate use-def chains, def-use chains, and reaching definitions, and perform other traditional data-flow analyses such as liveness analysis.

• I’ve always wanted to find a better name for this analysis. Now I gave up and decided to live with this name for the foreseeable future (until a better name is proposed by someone else).

• Aliasing is definitely a problem, and I forgot how aliasing is resolved in this implementation. I’ll leave this as a post-graduation TODO.

• Some more documentation and examples would be nice.

__init__(subject=None, func_graph=None, max_iterations=3, track_tmps=False, track_consts=True, observation_points=None, init_state=None, init_context=None, cc=None, function_handler=None, observe_all=False, visited_blocks=None, dep_graph=True, observe_callback=None, canonical_size=8, stack_pointer_tracker=None)

Parameters:

• subject (Union[Subject, Block, Block, Function, str, None]) – The subject of the analysis: a function, or a single basic block

• func_graph – Alternative graph for function.graph.

• max_iterations – The maximum number of iterations before the analysis is terminated.

• track_tmps – Whether or not temporary variables should be taken into consideration during the analysis.

• observation_points (iterable) – A collection of tuples of (“node”|”insn”, ins_addr, OP_TYPE) defining where reaching definitions should be copied and stored. OP_TYPE can be OP_BEFORE or OP_AFTER.

• init_state (Optional[ReachingDefinitionsState]) – An optional initialization state. The analysis creates and works on a copy. Default to None: the analysis then initialize its own abstract state, based on the given <Subject>.

• init_context – If init_state is not given, this is used to initialize the context field of the initial state’s CodeLocation. The only default-supported type which may go here is a tuple of integers, i.e. a callstack. Anything else requires a custom FunctionHandler.

• cc – Calling convention of the function.

• function_handler (Optional[FunctionHandler]) – The function handler to update the analysis state and results on function calls.

• observe_all – Observe every statement, both before and after.

• visited_blocks – A set of previously visited blocks.

• dep_graph (Union[DepGraph, bool, None]) – An initial dependency graph to add the result of the analysis to. Set it to None to skip dependency graph generation.

• canonical_size – The sizes (in bytes) that objects with an UNKNOWN_SIZE are treated as for operations where sizes are necessary.

• dep_graph – Set this to True to generate a dependency graph for the subject. It will be available as result.dep_graph.

property observed_results: Dict[Tuple[str, int, int], LiveDefinitions]

property all_definitions

property all_uses

property one_result

property dep_graph: DepGraph

property visited_blocks

get_reaching_definitions(**kwargs)

get_reaching_definitions_by_insn(ins_addr, op_type)

get_reaching_definitions_by_node(node_addr, op_type)

node_observe(node_addr, state, op_type)

Parameters:

• node_addr (int) – Address of the node.

• state (ReachingDefinitionsState) – The analysis state.

• op_type (ObservationPointType) – Type of the bbservation point. Must be one of the following: OP_BEFORE, OP_AFTER.

Return type:

None

insn_observe(insn_addr, stmt, block, state, op_type)

Parameters:

• insn_addr (int) – Address of the instruction.

• stmt (Union[Statement, IRStmt]) – The statement.

• block (Union[Block, Block]) – The current block.

• state (ReachingDefinitionsState) – The abstract analysis state.

• op_type (ObservationPointType) – Type of the observation point. Must be one of the following: OP_BEORE, OP_AFTER.

Return type:

None

stmt_observe(stmt_idx, stmt, block, state, op_type)

Parameters:

• stmt_idx (int) –

• stmt (Union[Statement, IRStmt]) –

• block (Union[Block, Block]) –

• state (ReachingDefinitionsState) –

• op_type (ObservationPointType) –

Return type:

None

Returns:

property subject

abort()

Abort the analysis :return: None

downsize()

errors = []

property graph: DiGraph

has_job(job)

Checks whether there exists another job which has the same job key. :type job: TypeVar(JobType) :param job: The job to check.

Return type:

bool

Returns:

True if there exists another job with the same key, False otherwise.

Parameters:

job (JobType) –

property jobs

named_errors = {}

property should_abort

Should the analysis be terminated. :return: True/False

project: Project

kb: KnowledgeBase

callsites_to(target)

Return type:

Iterable[FunctionCallRelationships]

Parameters:

target (int | str | Function) –

class angr.analyses.reaching_definitions.ReachingDefinitionsModel(func_addr=None)

Bases: object

Models the definitions, uses, and memory of a ReachingDefinitionState object

Parameters:

func_addr (int | None) –

__init__(func_addr=None)

Parameters:

func_addr (int | None) –

copy()

Return type:

ReachingDefinitionsModel

merge(model)

Parameters:

model (ReachingDefinitionsModel) –

get_observation_by_insn(ins_addr, kind)

Return type:

Optional[LiveDefinitions]

Parameters:

• ins_addr (int | CodeLocation) –

• kind (ObservationPointType) –

get_observation_by_node(node_addr, kind)

Return type:

Optional[LiveDefinitions]

Parameters:

• node_addr (int | CodeLocation) –

• kind (ObservationPointType) –

get_observation_by_stmt(arg1, arg2, arg3=None, *, block_idx=None)

class angr.analyses.reaching_definitions.ReachingDefinitionsState(codeloc, arch, subject, track_tmps=False, track_consts=False, analysis=None, rtoc_value=None, live_definitions=None, canonical_size=8, heap_allocator=None, environment=None, sp_adjusted=False, all_definitions=None)

Bases: object

Represents the internal state of the ReachingDefinitionsAnalysis.

It contains a data class LiveDefinitions, which stores both definitions and uses for register, stack, memory, and temporary variables, uncovered during the analysis.

Parameters:

• subject (Subject) – The subject being analyzed.

• track_tmps (bool) – Only tells whether or not temporary variables should be taken into consideration when representing the state of the analysis. Should be set to true when the analysis has counted uses and definitions for temporary variables, false otherwise.

• analysis (Optional[ReachingDefinitionsAnalysis]) – The analysis that generated the state represented by this object.

• rtoc_value – When the targeted architecture is ppc64, the initial function needs to know the rtoc_value.

• live_definitions (Optional[LiveDefinitions]) –

• canonical_size (int) – The sizes (in bytes) that objects with an UNKNOWN_SIZE are treated as for operations where sizes are necessary.

• heap_allocator (Optional[HeapAllocator]) – Mechanism to model the management of heap memory.

• environment (Optional[Environment]) – Representation of the environment of the analyzed program.

• codeloc (CodeLocation) –

• arch (Arch) –

• track_consts (bool) –

• sp_adjusted (bool) –

• all_definitions (Set[Definition] | None) –

Variables:

arch – The architecture targeted by the program.

__init__(codeloc, arch, subject, track_tmps=False, track_consts=False, analysis=None, rtoc_value=None, live_definitions=None, canonical_size=8, heap_allocator=None, environment=None, sp_adjusted=False, all_definitions=None)

Parameters:

• codeloc (CodeLocation) –

• arch (Arch) –

• subject (Subject) –

• track_tmps (bool) –

• track_consts (bool) –

• analysis (ReachingDefinitionsAnalysis | None) –

• live_definitions (LiveDefinitions | None) –

• canonical_size (int) –

• heap_allocator (HeapAllocator | None) –

• environment (Environment | None) –

• sp_adjusted (bool) –

• all_definitions (Set[Definition] | None) –

codeloc

arch: Arch

analysis

all_definitions: Set[Definition]

live_definitions

heap_allocator

codeloc_uses: Set[Definition]

exit_observed: bool

top(bits)

Parameters:

bits (int) –

is_top(*args)

heap_address(offset)

Return type:

Base

Parameters:

offset (int) –

static is_heap_address(addr)

Return type:

bool

Parameters:

addr (Base) –

static get_heap_offset(addr)

Return type:

Optional[int]

Parameters:

addr (Base) –

stack_address(offset)

Return type:

Base

Parameters:

offset (int) –

is_stack_address(addr)

Return type:

bool

Parameters:

addr (Base) –

get_stack_offset(addr)

Return type:

Optional[int]

Parameters:

addr (Base) –

annotate_with_def(symvar, definition)

Parameters:

• symvar (Base) –

• definition (Definition) –

Return type:

Base

Returns:

annotate_mv_with_def(mv, definition)

Return type:

MultiValues

Parameters:

• mv (MultiValues) –

• definition (Definition) –

extract_defs(symvar)

Return type:

Iterator[Definition]

Parameters:

symvar (Base) –

property tmp_definitions

property tmp_uses

property register_uses

property register_definitions: MultiValuedMemory

property stack_definitions: MultiValuedMemory

property stack_uses

property heap_definitions: MultiValuedMemory

property heap_uses

property memory_uses

property memory_definitions: MultiValuedMemory

property uses_by_codeloc

get_sp()

Return type:

int

get_stack_address(offset)

Return type:

int

Parameters:

offset (Base) –

property environment

property dep_graph

copy()

Return type:

ReachingDefinitionsState

merge(*others)

Return type:

Tuple[ReachingDefinitionsState, bool]

move_codelocs(new_codeloc)

Return type:

None

Parameters:

new_codeloc (CodeLocation) –

kill_definitions(atom)

Overwrite existing definitions w.r.t ‘atom’ with a dummy definition instance. A dummy definition will not be removed during simplification.

Return type:

None

Parameters:

atom (Atom) –

kill_and_add_definition(atom, data, dummy=False, tags=None, endness=None, annotated=False, uses=None, override_codeloc=None)

Return type:

Tuple[Optional[MultiValues], Set[Definition]]

Parameters:

• atom (Atom) –

• data (MultiValues) –

• tags (Set[Tag] | None) –

• annotated (bool) –

• uses (Set[Definition] | None) –

• override_codeloc (CodeLocation | None) –

add_use(atom, expr=None)

Return type:

None

Parameters:

• atom (Atom) –

• expr (Any | None) –

add_use_by_def(definition, expr=None)

Return type:

None

Parameters:

• definition (Definition) –

• expr (Any | None) –

add_tmp_use(tmp, expr=None)

Return type:

None

Parameters:

• tmp (int) –

• expr (Any | None) –

add_tmp_use_by_defs(defs, expr=None)

Return type:

None

Parameters:

• defs (Iterable[Definition]) –

• expr (Any | None) –

add_register_use(reg_offset, size, expr=None)

Return type:

None

Parameters:

• reg_offset (int) –

• size (int) –

• expr (Any | None) –

add_register_use_by_defs(defs, expr=None)

Return type:

None

Parameters:

• defs (Iterable[Definition]) –

• expr (Any | None) –

add_stack_use(stack_offset, size, endness, expr=None)

Return type:

None

Parameters:

• stack_offset (int) –

• size (int) –

• expr (Any | None) –

add_stack_use_by_defs(defs, expr=None)

Parameters:

• defs (Iterable[Definition]) –

• expr (Any | None) –

add_heap_use(heap_offset, size, endness, expr=None)

Return type:

None

Parameters:

• heap_offset (int) –

• size (int) –

• expr (Any | None) –

add_heap_use_by_defs(defs, expr=None)

Parameters:

• defs (Iterable[Definition]) –

• expr (Any | None) –

add_memory_use_by_def(definition, expr=None)

Parameters:

• definition (Definition) –

• expr (Any | None) –

add_memory_use_by_defs(defs, expr=None)

Parameters:

• defs (Iterable[Definition]) –

• expr (Any | None) –

get_definitions(atom)

Return type:

Iterable[Definition]

Parameters:

atom (Atom) –

get_values(spec)

Return type:

Optional[MultiValues]

Parameters:

spec (Atom | Definition) –

get_one_value(spec)

Return type:

Optional[Base]

Parameters:

spec (Atom | Definition) –

get_concrete_value(spec)

Return type:

Optional[int]

Parameters:

spec (Atom | Definition) –

mark_guard(target)

mark_const(value, size)

Parameters:

• value (int) –

• size (int) –

downsize()

pointer_to_atoms(pointer, size, endness)

Given a MultiValues, return the set of atoms that loading or storing to the pointer with that value could define or use.

Return type:

Set[MemoryLocation]

Parameters:

• pointer (MultiValues) –

• size (int) –

• endness (str) –

pointer_to_atom(value, size, endness)

Return type:

Optional[MemoryLocation]

Parameters:

• value (Base) –

• size (int) –

• endness (str) –

class angr.analyses.reaching_definitions.FunctionHandler

Bases: object

A mechanism for summarizing a function call’s effect on a program for ReachingDefinitionsAnalysis.

hook(analysis)

Attach this instance of the function handler to an instance of RDA.

Return type:

FunctionHandler

Parameters:

analysis (ReachingDefinitionsAnalysis) –

make_function_codeloc(target, callsite, callsite_func_addr)

The RDA engine will call this function to transform a callsite CodeLocation into a callee CodeLocation.

Parameters:

• target (None | int | MultiValues) –

• callsite (CodeLocation) –

• callsite_func_addr (int | None) –

handle_function(state, data)

The main entry point for the function handler. Called with a RDA state and a FunctionCallData, it is expected to update the state and the data as per the contracts described on FunctionCallData.

You can override this method to take full control over how data is processed, or override any of the following to use the higher-level interface (data.depends()):

• handle_impl_<function name>

• handle_local_function

• handle_external_function

• handle_indirect_function

• handle_generic_function

Each of them take the same signature as handle_function.

Parameters:

• state (ReachingDefinitionsState) –

• data (FunctionCallData) –

handle_generic_function(state, data)

Parameters:

• state (ReachingDefinitionsState) –

• data (FunctionCallData) –

handle_indirect_function(state, data)

Parameters:

• state (ReachingDefinitionsState) –

• data (FunctionCallData) –

handle_local_function(state, data)

Parameters:

• state (ReachingDefinitionsState) –

• data (FunctionCallData) –

handle_external_function(state, data)

Parameters:

• state (ReachingDefinitionsState) –

• data (FunctionCallData) –

static c_args_as_atoms(state, cc, prototype)

Return type:

List[Set[Atom]]

Parameters:

• state (ReachingDefinitionsState) –

• cc (SimCC) –

• prototype (SimTypeFunction) –

static c_return_as_atoms(state, cc, prototype)

Return type:

Set[Atom]

Parameters:

• state (ReachingDefinitionsState) –

• cc (SimCC) –

• prototype (SimTypeFunction) –

static caller_saved_regs_as_atoms(state, cc)

Return type:

Set[Register]

Parameters:

• state (ReachingDefinitionsState) –

• cc (SimCC) –

static stack_pointer_as_atom(state)

Return type:

Register

class angr.analyses.reaching_definitions.FunctionCallData(callsite_codeloc, function_codeloc, address_multi, address=None, symbol=None, function=None, name=None, cc=None, prototype=None, args_atoms=None, args_values=None, ret_atoms=None, redefine_locals=True, visited_blocks=None, effects=<factory>, ret_values=None, ret_values_deps=None, caller_will_handle_single_ret=False, guessed_cc=False, guessed_prototype=False, retaddr_popped=False)

Bases: object

A bundle of intermediate data used when computing the sum effect of a function during ReachingDefinitionsAnalysis.

RDA engine contract:

• Construct one of these before calling FunctionHandler.handle_function. Fill it with as many fields as you can realistically provide without duplicating effort.

• Provide callsite_codeloc as either the call statement (AIL) or the default exit of the default statement of the calling block (VEX)

• Provide function_codeloc as the callee address with stmt_idx=0`.

Function handler contract:

• If redefine_locals is unset, do not adjust any artifacts of the function call abstration, such as the stack pointer, the caller saved registers, etc.

• If caller_will_handle_single_ret is set, and there is a single entry in ret_atoms, do not apply to the state effects modifying this atom. Instead, set ret_values and ret_values_deps to the values and deps which are used constructing these values.

Parameters:

• callsite_codeloc (CodeLocation) –

• function_codeloc (CodeLocation) –

• address_multi (MultiValues | None) –

• address (int | None) –

• symbol (Symbol | None) –

• function (Function | None) –

• name (str | None) –

• cc (SimCC | None) –

• prototype (SimTypeFunction | None) –

• args_atoms (List[Set[Atom]] | None) –

• args_values (List[MultiValues] | None) –

• ret_atoms (Set[Atom] | None) –

• redefine_locals (bool) –

• visited_blocks (Set[int] | None) –

• effects (List[FunctionEffect]) –

• ret_values (MultiValues | None) –

• ret_values_deps (Set[Definition] | None) –

• caller_will_handle_single_ret (bool) –

• guessed_cc (bool) –

• guessed_prototype (bool) –

• retaddr_popped (bool) –

callsite_codeloc: CodeLocation

function_codeloc: CodeLocation

address_multi: Optional[MultiValues]

address: Optional[int] = None

symbol: Optional[Symbol] = None

function: Optional[Function] = None

name: Optional[str] = None

cc: Optional[SimCC] = None

prototype: Optional[SimTypeFunction] = None

args_atoms: Optional[List[Set[Atom]]] = None

args_values: Optional[List[MultiValues]] = None

ret_atoms: Optional[Set[Atom]] = None

redefine_locals: bool = True

visited_blocks: Optional[Set[int]] = None

effects: List[FunctionEffect]

ret_values: Optional[MultiValues] = None

ret_values_deps: Optional[Set[Definition]] = None

caller_will_handle_single_ret: bool = False

guessed_cc: bool = False

guessed_prototype: bool = False

retaddr_popped: bool = False

has_clobbered(dest)

Determines whether the given atom already has effects applied

Return type:

bool

Parameters:

dest (Atom) –

depends(dest, *sources, value=None, apply_at_callsite=False)

Mark a single effect of the current function, including the atom being modified, the input atoms on which that output atom depends, the precise (or imprecise!) value to store, and whether the effect should be applied during the function or afterwards, at the callsite.

The atom being modified may be None to mark uses of the source atoms which do not have any explicit sinks.

Parameters:

• dest (Atom | None) –

• sources (Atom) –

• value (MultiValues | None) –

• apply_at_callsite (bool) –

__init__(callsite_codeloc, function_codeloc, address_multi, address=None, symbol=None, function=None, name=None, cc=None, prototype=None, args_atoms=None, args_values=None, ret_atoms=None, redefine_locals=True, visited_blocks=None, effects=<factory>, ret_values=None, ret_values_deps=None, caller_will_handle_single_ret=False, guessed_cc=False, guessed_prototype=False, retaddr_popped=False)

Parameters:

• callsite_codeloc (CodeLocation) –

• function_codeloc (CodeLocation) –

• address_multi (MultiValues | None) –

• address (int | None) –

• symbol (Symbol | None) –

• function (Function | None) –

• name (str | None) –

• cc (SimCC | None) –

• prototype (SimTypeFunction | None) –

• args_atoms (List[Set[Atom]] | None) –

• args_values (List[MultiValues] | None) –

• ret_atoms (Set[Atom] | None) –

• redefine_locals (bool) –

• visited_blocks (Set[int] | None) –

• effects (List[FunctionEffect]) –

• ret_values (MultiValues | None) –

• ret_values_deps (Set[Definition] | None) –

• caller_will_handle_single_ret (bool) –

• guessed_cc (bool) –

• guessed_prototype (bool) –

• retaddr_popped (bool) –

Return type:

None

angr.analyses.reaching_definitions.get_all_definitions(region)

Return type:

Set[Definition]

Parameters:

region (MultiValuedMemory) –

class angr.analyses.reaching_definitions.ExternalCodeLocation(call_string=None)

Bases: CodeLocation

Stands for a program point that originates from outside an analysis’ scope. i.e. a value loaded from rdi in a callee where the caller has not been analyzed.

Parameters:

call_string (Tuple[int, ...]) –

__init__(call_string=None)

Constructor.

Parameters:

• block_addr – Address of the block

• stmt_idx – Statement ID. None for SimProcedures or if the code location is meant to refer to the entire block.

• sim_procedure (class) – The corresponding SimProcedure class.

• ins_addr – The instruction address.

• context – A tuple that represents the context of this CodeLocation in contextful mode, or None in contextless mode.

• kwargs – Optional arguments, will be stored, but not used in __eq__ or __hash__.

• call_string (Tuple[int, ...] | None) –

call_string

block_addr: int

block_idx

context: Optional[Tuple[int]]

info: Optional[Dict]

ins_addr: Optional[int]

property short_repr

sim_procedure

stmt_idx: Optional[int]

class angr.analyses.reaching_definitions.call_trace.CallSite(caller_func_addr, block_addr, callee_func_addr)

Bases: object

Describes a call site on a CFG.

Parameters:

• caller_func_addr (int) –

• block_addr (int | None) –

• callee_func_addr (int) –

__init__(caller_func_addr, block_addr, callee_func_addr)

Parameters:

• caller_func_addr (int) –

• block_addr (int | None) –

• callee_func_addr (int) –

caller_func_addr

callee_func_addr

block_addr

class angr.analyses.reaching_definitions.call_trace.CallTrace(target)

Bases: object

Describes a series of functions calls to get from one function (current_function_address()) to another function or a basic block (self.target).

Parameters:

target (int) –

__init__(target)

Parameters:

target (int) –

target

callsites: List[CallSite]

current_function_address()

Return type:

int

step_back(caller_func_addr, block_addr, callee_func_addr)

Return type:

CallTrace

Parameters:

• caller_func_addr (int) –

• block_addr (int | None) –

includes_function(func_addr)

Return type:

bool

Parameters:

func_addr (int) –

copy()

Return type:

CallTrace

class angr.analyses.reaching_definitions.engine_vex.SimEngineRDVEX(project, functions=None, function_handler=None)

Bases: SimEngineLightVEXMixin, SimEngineLight

Implements the VEX execution engine for reaching definition analysis.

__init__(project, functions=None, function_handler=None)

process(state, *args, block=None, fail_fast=False, visited_blocks=None, dep_graph=None, **kwargs)

The main entry point for an engine. Should take a state and return a result.

Parameters:

state – The state to proceed from

Returns:

The result. Whatever you want ;)

static extract_offset_to_sp(spoffset_expr)

Extract the offset to the original stack pointer.

Parameters:

spoffset_expr (Base) – The claripy AST to parse.

Return type:

Optional[int]

Returns:

The offset to the original stack pointer, or None if spoffset_expr is not a supported type of SpOffset expression.

static sp_offset(bits, offset)

Parameters:

• bits (int) –

• offset (int) –

class angr.analyses.reaching_definitions.reaching_definitions.ReachingDefinitionsAnalysis(subject=None, func_graph=None, max_iterations=3, track_tmps=False, track_consts=True, observation_points=None, init_state=None, init_context=None, cc=None, function_handler=None, observe_all=False, visited_blocks=None, dep_graph=True, observe_callback=None, canonical_size=8, stack_pointer_tracker=None)

Bases: ForwardAnalysis[ReachingDefinitionsState, NodeType, object, object], Analysis

ReachingDefinitionsAnalysis is a text-book implementation of a static data-flow analysis that works on either a function or a block. It supports both VEX and AIL. By registering observers to observation points, users may use this analysis to generate use-def chains, def-use chains, and reaching definitions, and perform other traditional data-flow analyses such as liveness analysis.

• I’ve always wanted to find a better name for this analysis. Now I gave up and decided to live with this name for the foreseeable future (until a better name is proposed by someone else).

• Aliasing is definitely a problem, and I forgot how aliasing is resolved in this implementation. I’ll leave this as a post-graduation TODO.

• Some more documentation and examples would be nice.

__init__(subject=None, func_graph=None, max_iterations=3, track_tmps=False, track_consts=True, observation_points=None, init_state=None, init_context=None, cc=None, function_handler=None, observe_all=False, visited_blocks=None, dep_graph=True, observe_callback=None, canonical_size=8, stack_pointer_tracker=None)

Parameters:

• subject (Union[Subject, Block, Block, Function, str, None]) – The subject of the analysis: a function, or a single basic block

• func_graph – Alternative graph for function.graph.

• max_iterations – The maximum number of iterations before the analysis is terminated.

• track_tmps – Whether or not temporary variables should be taken into consideration during the analysis.

• observation_points (iterable) – A collection of tuples of (“node”|”insn”, ins_addr, OP_TYPE) defining where reaching definitions should be copied and stored. OP_TYPE can be OP_BEFORE or OP_AFTER.

• init_state (Optional[ReachingDefinitionsState]) – An optional initialization state. The analysis creates and works on a copy. Default to None: the analysis then initialize its own abstract state, based on the given <Subject>.

• init_context – If init_state is not given, this is used to initialize the context field of the initial state’s CodeLocation. The only default-supported type which may go here is a tuple of integers, i.e. a callstack. Anything else requires a custom FunctionHandler.

• cc – Calling convention of the function.

• function_handler (Optional[FunctionHandler]) – The function handler to update the analysis state and results on function calls.

• observe_all – Observe every statement, both before and after.

• visited_blocks – A set of previously visited blocks.

• dep_graph (Union[DepGraph, bool, None]) – An initial dependency graph to add the result of the analysis to. Set it to None to skip dependency graph generation.

• canonical_size – The sizes (in bytes) that objects with an UNKNOWN_SIZE are treated as for operations where sizes are necessary.

• dep_graph – Set this to True to generate a dependency graph for the subject. It will be available as result.dep_graph.

model: ReachingDefinitionsModel

function_calls: Dict[CodeLocation, FunctionCallRelationships]

property observed_results: Dict[Tuple[str, int, int], LiveDefinitions]

property all_definitions

property all_uses

property one_result

property dep_graph: DepGraph

property visited_blocks

get_reaching_definitions(**kwargs)

get_reaching_definitions_by_insn(ins_addr, op_type)

get_reaching_definitions_by_node(node_addr, op_type)

node_observe(node_addr, state, op_type)

Parameters:

• node_addr (int) – Address of the node.

• state (ReachingDefinitionsState) – The analysis state.

• op_type (ObservationPointType) – Type of the bbservation point. Must be one of the following: OP_BEFORE, OP_AFTER.

Return type:

None

insn_observe(insn_addr, stmt, block, state, op_type)

Parameters:

• insn_addr (int) – Address of the instruction.

• stmt (Union[Statement, IRStmt]) – The statement.

• block (Union[Block, Block]) – The current block.

• state (ReachingDefinitionsState) – The abstract analysis state.

• op_type (ObservationPointType) – Type of the observation point. Must be one of the following: OP_BEORE, OP_AFTER.

Return type:

None

stmt_observe(stmt_idx, stmt, block, state, op_type)

Parameters:

• stmt_idx (int) –

• stmt (Union[Statement, IRStmt]) –

• block (Union[Block, Block]) –

• state (ReachingDefinitionsState) –

• op_type (ObservationPointType) –

Return type:

None

Returns:

property subject

abort()

Abort the analysis :return: None

downsize()

errors = []

property graph: DiGraph

has_job(job)

Checks whether there exists another job which has the same job key. :type job: TypeVar(JobType) :param job: The job to check.

Return type:

bool

Returns:

True if there exists another job with the same key, False otherwise.

Parameters:

job (JobType) –

property jobs

named_errors = {}

property should_abort

Should the analysis be terminated. :return: True/False

project: Project

kb: KnowledgeBase

callsites_to(target)

Return type:

Iterable[FunctionCallRelationships]

Parameters:

target (int | str | Function) –

class angr.analyses.reaching_definitions.dep_graph.FunctionCallRelationships(callsite, target, args_defns, other_input_defns, ret_defns, other_output_defns)

Bases: object

Parameters:

• callsite (CodeLocation) –

• target (int | None) –

• args_defns (List[Set[Definition]]) –

• other_input_defns (Set[Definition]) –

• ret_defns (Set[Definition]) –

• other_output_defns (Set[Definition]) –

callsite: CodeLocation

target: Optional[int]

args_defns: List[Set[Definition]]

other_input_defns: Set[Definition]

ret_defns: Set[Definition]

other_output_defns: Set[Definition]

__init__(callsite, target, args_defns, other_input_defns, ret_defns, other_output_defns)

Parameters:

• callsite (CodeLocation) –

• target (int | None) –

• args_defns (List[Set[Definition]]) –

• other_input_defns (Set[Definition]) –

• ret_defns (Set[Definition]) –

• other_output_defns (Set[Definition]) –

Return type:

None

class angr.analyses.reaching_definitions.dep_graph.DepGraph(graph=None)

Bases: object

The representation of a dependency graph: a directed graph, where nodes are definitions, and edges represent uses.

Mostly a wrapper around a <networkx.DiGraph>.

Parameters:

graph (DiGraph | None) –

__init__(graph=None)

Parameters:

graph (Optional[DiGraph]) – A graph where nodes are definitions, and edges represent uses.

property graph: DiGraph

add_node(node)

Parameters:

node (Definition) – The definition to add to the definition-use graph.

Return type:

None

add_edge(source, destination, **labels)

The edge to add to the definition-use graph. Will create nodes that are not yet present.

Parameters:

• source (Definition) – The “source” definition, used by the “destination”.

• destination (Definition) – The “destination” definition, using the variable defined by “source”.

• labels – Optional keyword arguments to represent edge labels.

Return type:

None

nodes()

Return type:

NodeView

predecessors(node)

Parameters:

node (Definition) – The definition to get the predecessors of.

Return type:

NodeView

transitive_closure(definition)

Compute the “transitive closure” of a given definition. Obtained by transitively aggregating the ancestors of this definition in the graph.

Note: Each definition is memoized to avoid any kind of recomputation across the lifetime of this object.

Parameters:

definition (Definition) – The Definition to get transitive closure for.

Return type:

DiGraph

Returns:

A graph of the transitive closure of the given definition.

contains_atom(atom)

Return type:

bool

Parameters:

atom (Atom) –

add_dependencies_for_concrete_pointers_of(values, definition, cfg, loader)

When a given definition holds concrete pointers, make sure the <MemoryLocation>s they point to are present in the dependency graph; Adds them if necessary.

Parameters:

• values (Iterable[Union[Base, int]]) –

• definition (Definition) – The definition which has data that can contain concrete pointers.

• cfg (CFGModel) – The CFG, containing information about memory data.

• loader (Loader) –

find_definitions(**kwargs)

Filter the definitions present in the graph based on various criteria. Parameters can be any valid keyword args to DefinitionMatchPredicate

Return type:

List[Definition]

find_all_predecessors(starts, **kwargs)

Filter the ancestors of the given start node or nodes that match various criteria. Parameters can be any valid keyword args to DefinitionMatchPredicate

find_all_successors(starts, **kwargs)

Filter the descendents of the given start node or nodes that match various criteria. Parameters can be any valid keyword args to DefinitionMatchPredicate

Return type:

List[Definition]

Parameters:

starts (Definition | Iterable[Definition]) –

find_path(starts, ends, **kwargs)

Find a path between the given start node or nodes and the given end node or nodes. All the intermediate steps in the path must match the criteria given in kwargs. The kwargs can be any valid parameters to DefinitionMatchPredicate.

This algorithm has exponential time and space complexity. Use at your own risk. Want to do better? Do it yourself or use networkx and eat the cost of indirection and/or cloning.

Return type:

Optional[Tuple[Definition, ...]]

Parameters:

• starts (Definition | Iterable[Definition]) –

• ends (Definition | Iterable[Definition]) –

find_paths(starts, ends, **kwargs)

Find all non-overlapping simple paths between the given start node or nodes and the given end node or nodes. All the intermediate steps in the path must match the criteria given in kwargs. The kwargs can be any valid parameters to DefinitionMatchPredicate.

This algorithm has exponential time and space complexity. Use at your own risk. Want to do better? Do it yourself or use networkx and eat the cost of indirection and/or cloning.

Return type:

Iterable[Tuple[Definition, ...]]

Parameters:

• starts (Definition | Iterable[Definition]) –

• ends (Definition | Iterable[Definition]) –

class angr.analyses.reaching_definitions.heap_allocator.HeapAllocator(canonical_size)

Bases: object

A simple modelisation to help represent heap memory management during a <ReachingDefinitionsAnalysis>: - Act as if allocations were always done in consecutive memory segments; - Take care of the size not to screw potential pointer arithmetic (avoid overlapping segments).

The content of the heap itself is modeled using a <KeyedRegion> attribute in the <LiveDefinitions> state; This class serves to generate consistent heap addresses to be used by the aforementionned.

Note: This has NOT been made to help detect heap vulnerabilities.

Parameters:

canonical_size (int) –

__init__(canonical_size)

Parameters:

canonical_size (int) – The concrete size an <UNKNOWN_SIZE> defaults to.

allocate(size)

Gives an address for a new memory chunck of <size> bytes.

Parameters:

size (Union[int, UnknownSize]) – The requested size for the chunck, in number of bytes.

Return type:

HeapAddress

Returns:

The address of the chunck.

free(address)

Mark the chunck pointed by <address> as freed.

Parameters:

address (Union[Undefined, HeapAddress]) – The address of the chunck to free.

property allocated_addresses

The list of addresses that are currently allocated on the heap.

Type:

return

class angr.analyses.reaching_definitions.function_handler.FunctionEffect(dest, sources, value=None, sources_defns=None, apply_at_callsite=False)

Bases: object

A single effect that a function summary may apply to the state. This is largely an implementation detail; use FunctionCallData.depends instead.

Parameters:

• dest (Atom | None) –

• sources (Set[Atom]) –

• value (MultiValues | None) –

• sources_defns (Set[Definition] | None) –

• apply_at_callsite (bool) –

dest: Optional[Atom]

sources: Set[Atom]

value: Optional[MultiValues] = None

sources_defns: Optional[Set[Definition]] = None

apply_at_callsite: bool = False

__init__(dest, sources, value=None, sources_defns=None, apply_at_callsite=False)

Parameters:

• dest (Atom | None) –

• sources (Set[Atom]) –

• value (MultiValues | None) –

• sources_defns (Set[Definition] | None) –

• apply_at_callsite (bool) –

Return type:

None

class angr.analyses.reaching_definitions.function_handler.FunctionCallData(callsite_codeloc, function_codeloc, address_multi, address=None, symbol=None, function=None, name=None, cc=None, prototype=None, args_atoms=None, args_values=None, ret_atoms=None, redefine_locals=True, visited_blocks=None, effects=<factory>, ret_values=None, ret_values_deps=None, caller_will_handle_single_ret=False, guessed_cc=False, guessed_prototype=False, retaddr_popped=False)

Bases: object

A bundle of intermediate data used when computing the sum effect of a function during ReachingDefinitionsAnalysis.

RDA engine contract:

• Construct one of these before calling FunctionHandler.handle_function. Fill it with as many fields as you can realistically provide without duplicating effort.

• Provide callsite_codeloc as either the call statement (AIL) or the default exit of the default statement of the calling block (VEX)

• Provide function_codeloc as the callee address with stmt_idx=0`.

Function handler contract:

• If redefine_locals is unset, do not adjust any artifacts of the function call abstration, such as the stack pointer, the caller saved registers, etc.

• If caller_will_handle_single_ret is set, and there is a single entry in ret_atoms, do not apply to the state effects modifying this atom. Instead, set ret_values and ret_values_deps to the values and deps which are used constructing these values.

Parameters:

• callsite_codeloc (CodeLocation) –

• function_codeloc (CodeLocation) –

• address_multi (MultiValues | None) –

• address (int | None) –

• symbol (Symbol | None) –

• function (Function | None) –

• name (str | None) –

• cc (SimCC | None) –

• prototype (SimTypeFunction | None) –

• args_atoms (List[Set[Atom]] | None) –

• args_values (List[MultiValues] | None) –

• ret_atoms (Set[Atom] | None) –

• redefine_locals (bool) –

• visited_blocks (Set[int] | None) –

• effects (List[FunctionEffect]) –

• ret_values (MultiValues | None) –

• ret_values_deps (Set[Definition] | None) –

• caller_will_handle_single_ret (bool) –

• guessed_cc (bool) –

• guessed_prototype (bool) –

• retaddr_popped (bool) –

callsite_codeloc: CodeLocation

function_codeloc: CodeLocation

address_multi: Optional[MultiValues]

address: Optional[int] = None

symbol: Optional[Symbol] = None

function: Optional[Function] = None

name: Optional[str] = None

cc: Optional[SimCC] = None

prototype: Optional[SimTypeFunction] = None

args_atoms: Optional[List[Set[Atom]]] = None

args_values: Optional[List[MultiValues]] = None

ret_atoms: Optional[Set[Atom]] = None

redefine_locals: bool = True

visited_blocks: Optional[Set[int]] = None

effects: List[FunctionEffect]

ret_values: Optional[MultiValues] = None

ret_values_deps: Optional[Set[Definition]] = None

caller_will_handle_single_ret: bool = False

guessed_cc: bool = False

guessed_prototype: bool = False

retaddr_popped: bool = False

has_clobbered(dest)

Determines whether the given atom already has effects applied

Return type:

bool

Parameters:

dest (Atom) –

depends(dest, *sources, value=None, apply_at_callsite=False)

Mark a single effect of the current function, including the atom being modified, the input atoms on which that output atom depends, the precise (or imprecise!) value to store, and whether the effect should be applied during the function or afterwards, at the callsite.

The atom being modified may be None to mark uses of the source atoms which do not have any explicit sinks.

Parameters:

• dest (Atom | None) –

• sources (Atom) –

• value (MultiValues | None) –

• apply_at_callsite (bool) –

__init__(callsite_codeloc, function_codeloc, address_multi, address=None, symbol=None, function=None, name=None, cc=None, prototype=None, args_atoms=None, args_values=None, ret_atoms=None, redefine_locals=True, visited_blocks=None, effects=<factory>, ret_values=None, ret_values_deps=None, caller_will_handle_single_ret=False, guessed_cc=False, guessed_prototype=False, retaddr_popped=False)

Parameters:

• callsite_codeloc (CodeLocation) –

• function_codeloc (CodeLocation) –

• address_multi (MultiValues | None) –

• address (int | None) –

• symbol (Symbol | None) –

• function (Function | None) –

• name (str | None) –

• cc (SimCC | None) –

• prototype (SimTypeFunction | None) –

• args_atoms (List[Set[Atom]] | None) –

• args_values (List[MultiValues] | None) –

• ret_atoms (Set[Atom] | None) –

• redefine_locals (bool) –

• visited_blocks (Set[int] | None) –

• effects (List[FunctionEffect]) –

• ret_values (MultiValues | None) –

• ret_values_deps (Set[Definition] | None) –

• caller_will_handle_single_ret (bool) –

• guessed_cc (bool) –

• guessed_prototype (bool) –

• retaddr_popped (bool) –

Return type:

None

class angr.analyses.reaching_definitions.function_handler.FunctionHandler

Bases: object

A mechanism for summarizing a function call’s effect on a program for ReachingDefinitionsAnalysis.

hook(analysis)

Attach this instance of the function handler to an instance of RDA.

Return type:

FunctionHandler

Parameters:

analysis (ReachingDefinitionsAnalysis) –

make_function_codeloc(target, callsite, callsite_func_addr)

The RDA engine will call this function to transform a callsite CodeLocation into a callee CodeLocation.

Parameters:

• target (None | int | MultiValues) –

• callsite (CodeLocation) –

• callsite_func_addr (int | None) –

handle_function(state, data)

The main entry point for the function handler. Called with a RDA state and a FunctionCallData, it is expected to update the state and the data as per the contracts described on FunctionCallData.

You can override this method to take full control over how data is processed, or override any of the following to use the higher-level interface (data.depends()):

• handle_impl_<function name>

• handle_local_function

• handle_external_function

• handle_indirect_function

• handle_generic_function

Each of them take the same signature as handle_function.

Parameters:

• state (ReachingDefinitionsState) –

• data (FunctionCallData) –

handle_generic_function(state, data)

Parameters:

• state (ReachingDefinitionsState) –

• data (FunctionCallData) –

handle_indirect_function(state, data)

Parameters:

• state (ReachingDefinitionsState) –

• data (FunctionCallData) –

handle_local_function(state, data)

Parameters:

• state (ReachingDefinitionsState) –

• data (FunctionCallData) –

handle_external_function(state, data)

Parameters:

• state (ReachingDefinitionsState) –

• data (FunctionCallData) –

static c_args_as_atoms(state, cc, prototype)

Return type:

List[Set[Atom]]

Parameters:

• state (ReachingDefinitionsState) –

• cc (SimCC) –

• prototype (SimTypeFunction) –

static c_return_as_atoms(state, cc, prototype)

Return type:

Set[Atom]

Parameters:

• state (ReachingDefinitionsState) –

• cc (SimCC) –

• prototype (SimTypeFunction) –

static caller_saved_regs_as_atoms(state, cc)

Return type:

Set[Register]

Parameters:

• state (ReachingDefinitionsState) –

• cc (SimCC) –

static stack_pointer_as_atom(state)

Return type:

Register

class angr.analyses.reaching_definitions.rd_state.ReachingDefinitionsState(codeloc, arch, subject, track_tmps=False, track_consts=False, analysis=None, rtoc_value=None, live_definitions=None, canonical_size=8, heap_allocator=None, environment=None, sp_adjusted=False, all_definitions=None)

Bases: object

Represents the internal state of the ReachingDefinitionsAnalysis.

It contains a data class LiveDefinitions, which stores both definitions and uses for register, stack, memory, and temporary variables, uncovered during the analysis.

Parameters:

• subject (Subject) – The subject being analyzed.

• track_tmps (bool) – Only tells whether or not temporary variables should be taken into consideration when representing the state of the analysis. Should be set to true when the analysis has counted uses and definitions for temporary variables, false otherwise.

• analysis (Optional[ReachingDefinitionsAnalysis]) – The analysis that generated the state represented by this object.

• rtoc_value – When the targeted architecture is ppc64, the initial function needs to know the rtoc_value.

• live_definitions (Optional[LiveDefinitions]) –

• canonical_size (int) – The sizes (in bytes) that objects with an UNKNOWN_SIZE are treated as for operations where sizes are necessary.

• heap_allocator (Optional[HeapAllocator]) – Mechanism to model the management of heap memory.

• environment (Optional[Environment]) – Representation of the environment of the analyzed program.

• codeloc (CodeLocation) –

• arch (Arch) –

• track_consts (bool) –

• sp_adjusted (bool) –

• all_definitions (Set[Definition]) –

Variables:

arch – The architecture targeted by the program.

__init__(codeloc, arch, subject, track_tmps=False, track_consts=False, analysis=None, rtoc_value=None, live_definitions=None, canonical_size=8, heap_allocator=None, environment=None, sp_adjusted=False, all_definitions=None)

Parameters:

• codeloc (CodeLocation) –

• arch (Arch) –

• subject (Subject) –

• track_tmps (bool) –

• track_consts (bool) –

• analysis (ReachingDefinitionsAnalysis | None) –

• live_definitions (LiveDefinitions | None) –

• canonical_size (int) –

• heap_allocator (HeapAllocator | None) –

• environment (Environment | None) –

• sp_adjusted (bool) –

• all_definitions (Set[Definition] | None) –

codeloc

arch: Arch

analysis

all_definitions: Set[Definition]

live_definitions

heap_allocator

codeloc_uses: Set[Definition]

exit_observed: bool

top(bits)

Parameters:

bits (int) –

is_top(*args)

heap_address(offset)

Return type:

Base

Parameters:

offset (int) –

static is_heap_address(addr)

Return type:

bool

Parameters:

addr (Base) –

static get_heap_offset(addr)

Return type:

Optional[int]

Parameters:

addr (Base) –

stack_address(offset)

Return type:

Base

Parameters:

offset (int) –

is_stack_address(addr)

Return type:

bool

Parameters:

addr (Base) –

get_stack_offset(addr)

Return type:

Optional[int]

Parameters:

addr (Base) –

annotate_with_def(symvar, definition)

Parameters:

• symvar (Base) –

• definition (Definition) –

Return type:

Base

Returns:

annotate_mv_with_def(mv, definition)

Return type:

MultiValues

Parameters:

• mv (MultiValues) –

• definition (Definition) –

extract_defs(symvar)

Return type:

Iterator[Definition]

Parameters:

symvar (Base) –

property tmp_definitions

property tmp_uses

property register_uses

property register_definitions: MultiValuedMemory

property stack_definitions: MultiValuedMemory

property stack_uses

property heap_definitions: MultiValuedMemory

property heap_uses

property memory_uses

property memory_definitions: MultiValuedMemory

property uses_by_codeloc

get_sp()

Return type:

int

get_stack_address(offset)

Return type:

int

Parameters:

offset (Base) –

property environment

property dep_graph

copy()

Return type:

ReachingDefinitionsState

merge(*others)

Return type:

Tuple[ReachingDefinitionsState, bool]

move_codelocs(new_codeloc)

Return type:

None

Parameters:

new_codeloc (CodeLocation) –

kill_definitions(atom)

Overwrite existing definitions w.r.t ‘atom’ with a dummy definition instance. A dummy definition will not be removed during simplification.

Return type:

None

Parameters:

atom (Atom) –

kill_and_add_definition(atom, data, dummy=False, tags=None, endness=None, annotated=False, uses=None, override_codeloc=None)

Return type:

Tuple[Optional[MultiValues], Set[Definition]]

Parameters:

• atom (Atom) –

• data (MultiValues) –

• tags (Set[Tag] | None) –

• annotated (bool) –

• uses (Set[Definition] | None) –

• override_codeloc (CodeLocation | None) –

add_use(atom, expr=None)

Return type:

None

Parameters:

• atom (Atom) –

• expr (Any | None) –

add_use_by_def(definition, expr=None)

Return type:

None

Parameters:

• definition (Definition) –

• expr (Any | None) –

add_tmp_use(tmp, expr=None)

Return type:

None

Parameters:

• tmp (int) –

• expr (Any | None) –

add_tmp_use_by_defs(defs, expr=None)

Return type:

None

Parameters:

• defs (Iterable[Definition]) –

• expr (Any | None) –

add_register_use(reg_offset, size, expr=None)

Return type:

None

Parameters:

• reg_offset (int) –

• size (int) –

• expr (Any | None) –

add_register_use_by_defs(defs, expr=None)

Return type:

None

Parameters:

• defs (Iterable[Definition]) –

• expr (Any | None) –

add_stack_use(stack_offset, size, endness, expr=None)

Return type:

None

Parameters:

• stack_offset (int) –

• size (int) –

• expr (Any | None) –

add_stack_use_by_defs(defs, expr=None)

Parameters:

• defs (Iterable[Definition]) –

• expr (Any | None) –

add_heap_use(heap_offset, size, endness, expr=None)

Return type:

None

Parameters:

• heap_offset (int) –

• size (int) –

• expr (Any | None) –

add_heap_use_by_defs(defs, expr=None)

Parameters:

• defs (Iterable[Definition]) –

• expr (Any | None) –

add_memory_use_by_def(definition, expr=None)

Parameters:

• definition (Definition) –

• expr (Any | None) –

add_memory_use_by_defs(defs, expr=None)

Parameters:

• defs (Iterable[Definition]) –

• expr (Any | None) –

get_definitions(atom)

Return type:

Iterable[Definition]

Parameters:

atom (Atom) –

get_values(spec)

Return type:

Optional[MultiValues]

Parameters:

spec (Atom | Definition) –

get_one_value(spec)

Return type:

Optional[Base]

Parameters:

spec (Atom | Definition) –

get_concrete_value(spec)

Return type:

Optional[int]

Parameters:

spec (Atom | Definition) –

mark_guard(target)

mark_const(value, size)

Parameters:

• value (int) –

• size (int) –

downsize()

pointer_to_atoms(pointer, size, endness)

Given a MultiValues, return the set of atoms that loading or storing to the pointer with that value could define or use.

Return type:

Set[MemoryLocation]

Parameters:

• pointer (MultiValues) –

• size (int) –

• endness (str) –

pointer_to_atom(value, size, endness)

Return type:

Optional[MemoryLocation]

Parameters:

• value (Base) –

• size (int) –

• endness (str) –

class angr.analyses.reaching_definitions.subject.SubjectType(value)

Bases: Enum

An enumeration.

Function = 1

Block = 2

CallTrace = 3

class angr.analyses.reaching_definitions.subject.Subject(content, func_graph=None, cc=None)

Bases: object

__init__(content, func_graph=None, cc=None)

The thing being analysed, and the way (visitor) to analyse it.

Parameters:

• content (Union[ailment.Block, angr.Block, Function]) – Thing to be analysed.

• func_graph (networkx.DiGraph) – Alternative graph for function.graph.

• cc (SimCC) – Calling convention of the function.

property cc

property content

property func_graph

property type

property visitor: FunctionGraphVisitor | SingleNodeGraphVisitor

class angr.analyses.reaching_definitions.engine_ail.SimEngineRDAIL(project, function_handler=None, stack_pointer_tracker=None)

Bases: SimEngineLightAILMixin, SimEngineLight

Parameters:

function_handler (FunctionHandler | None) –

arch: Arch

state: ReachingDefinitionsState

__init__(project, function_handler=None, stack_pointer_tracker=None)

Parameters:

function_handler (FunctionHandler | None) –

process(state, *args, dep_graph=None, visited_blocks=None, block=None, fail_fast=False, **kwargs)

The main entry point for an engine. Should take a state and return a result.

Parameters:

state – The state to proceed from

Returns:

The result. Whatever you want ;)

static extract_offset_to_sp(spoffset_expr)

Extract the offset to the original stack pointer.

Parameters:

spoffset_expr (Base) – The claripy AST to parse.

Return type:

Optional[int]

Returns:

The offset to the original stack pointer, or None if spoffset_expr is not a supported type of SpOffset expression.

static sp_offset(bits, offset)

Parameters:

• bits (int) –

• offset (int) –

class angr.analyses.reaching_definitions.external_codeloc.ExternalCodeLocation(call_string=None)

Bases: CodeLocation

Stands for a program point that originates from outside an analysis’ scope. i.e. a value loaded from rdi in a callee where the caller has not been analyzed.

Parameters:

call_string (Tuple[int, ...]) –

__init__(call_string=None)

Constructor.

Parameters:

• block_addr – Address of the block

• stmt_idx – Statement ID. None for SimProcedures or if the code location is meant to refer to the entire block.

• sim_procedure (class) – The corresponding SimProcedure class.

• ins_addr – The instruction address.

• context – A tuple that represents the context of this CodeLocation in contextful mode, or None in contextless mode.

• kwargs – Optional arguments, will be stored, but not used in __eq__ or __hash__.

• call_string (Tuple[int, ...] | None) –

call_string

block_addr: int

block_idx

context: Optional[Tuple[int]]

info: Optional[Dict]

ins_addr: Optional[int]

property short_repr

sim_procedure

stmt_idx: Optional[int]

class angr.analyses.cfg_slice_to_sink.cfg_slice_to_sink.CFGSliceToSink(target, transitions=None)

Bases: object

The representation of a slice of a CFG.

__init__(target, transitions=None)

Parameters:

• target (angr.knowledge_plugins.functions.function.Function) – The targeted sink, to which every path in the slice leads.

• transitions (Dict[int,List[int]]) – A mapping representing transitions in the graph. Indexes are source addresses and values a list of destination addresses, for which there exists a transition in the slice from source to destination.

property transitions

The transitions in the slice.

Type:

return Dict[int,List[int]]

property transitions_as_tuples

The list of transitions as pairs of (source, destination).

Type:

return List[Tuple[int,int]]

property target

return angr.knowledge_plugins.functions.function.Function: The targeted sink function, from which the slice is constructed.

property nodes: List[int]

The complete list of addresses present in the slice.

Type:

return

property entrypoints

Entrypoints are all source addresses that are not the destination address of any transition.

Return List[int]:

The list of entrypoints addresses.

add_transitions(transitions)

Add the given transitions to the current slice.

Parameters:

transitions (Dict[int,List[int]]) – The list of transitions to be added to self.transitions.

Return Dict[int,List[int]]:

Return the updated list of transitions.

is_empty()

Test if a given slice does not contain any transition.

Return bool:

True if the <CFGSliceToSink> instance does not contain any transitions. False otherwise.

path_between(source, destination, visited=None)

Check the existence of a path in the slice between two given node adresses.

Parameters:

• source (int) – The source address.

• destination (int) – The destination address.

• visited (Optional[Set[Any]]) – Used to avoid infinite recursion if loops are present in the slice.

Return type:

bool

Returns:

True if there is a path between the source and the destination in the CFG, False if not, or if we have been unable to decide (because of loops).

angr.analyses.cfg_slice_to_sink.graph.slice_callgraph(callgraph, cfg_slice_to_sink)

Slice a callgraph, keeping only the nodes present in the <CFGSliceToSink> representation, and th transitions for which a path exists.

Note that this function mutates the graph passed as an argument.

Parameters:

• callgraph (networkx.MultiDiGraph) – The callgraph to update.

• cfg_slice_to_sink (CFGSliceToSink) – The representation of the slice, containing the data to update the callgraph from.

angr.analyses.cfg_slice_to_sink.graph.slice_cfg_graph(graph, cfg_slice_to_sink)

Slice a CFG graph, keeping only the transitions and nodes present in the <CFGSliceToSink> representation.

Note that this function mutates the graph passed as an argument.

Parameters:

• graph (networkx.DiGraph) – The graph to slice.

• cfg_slice_to_sink (CFGSliceToSink) – The representation of the slice, containing the data to update the CFG from.

Return networkx.DiGraph:

The sliced graph.

angr.analyses.cfg_slice_to_sink.graph.slice_function_graph(function_graph, cfg_slice_to_sink)

Slice a function graph, keeping only the nodes present in the <CFGSliceToSink> representation.

Because the <CFGSliceToSink> is build from the CFG, and the function graph is NOT a subgraph of the CFG, edges of the function graph will no be present in the <CFGSliceToSink> transitions. However, we use the fact that if there is an edge between two nodes in the function graph, then there must exist a path between these two nodes in the slice; Proof idea: - The <CFGSliceToSink> is backward and recursively constructed; - If a node is in the slice, then all its predecessors will be (transitively); - If there is an edge between two nodes in the function graph, there is a path between them in the CFG; - So: The origin node is a transitive predecessor of the destination one, hence if destination is in the slice, then origin will be too.

In consequence, in the end, removing the only nodes not present in the slice, and their related transitions gives us the expected result: a function graph representing (a higher view of) the flow in the slice.

Note that this function mutates the graph passed as an argument.

Parameters:

• graph (networkx.DiGraph) – The graph to slice.

• cfg_slice_to_sink (CFGSliceToSink) – The representation of the slice, containing the data to update the CFG from.

Return networkx.DiGraph:

The sliced graph.

Some utilitary functions to manage our representation of transitions:

A dictionary, indexed by int (source addresses), which values are list of ints (target addresses).

angr.analyses.cfg_slice_to_sink.transitions.merge_transitions(transitions, existing_transitions)

Merge two dictionaries of transitions together.

Parameters:

• transitions (Dict[int,List[int]]) – Some transitions.

• existing_transitions (Dict[int,List[int]]) – Other transitions.

Return Dict[int,List[int]]:

The merge of the two parameters.

class angr.analyses.stack_pointer_tracker.BottomType

Bases: object

The bottom value for register values.

class angr.analyses.stack_pointer_tracker.Constant(val)

Bases: object

Represents a constant value.

__init__(val)

val

class angr.analyses.stack_pointer_tracker.Register(offset, bitlen)

Bases: object

Represent a register.

__init__(offset, bitlen)

offset

bitlen

class angr.analyses.stack_pointer_tracker.OffsetVal(reg, offset)

Bases: object

Represent a value with an offset added.

__init__(reg, offset)

property reg

property offset

class angr.analyses.stack_pointer_tracker.FrozenStackPointerTrackerState(regs, memory, is_tracking_memory)

Bases: object

Abstract state for StackPointerTracker analysis with registers and memory values being in frozensets.

__init__(regs, memory, is_tracking_memory)

regs

memory

is_tracking_memory

unfreeze()

merge(other)

class angr.analyses.stack_pointer_tracker.StackPointerTrackerState(regs, memory, is_tracking_memory)

Bases: object

Abstract state for StackPointerTracker analysis.

__init__(regs, memory, is_tracking_memory)

regs

memory

is_tracking_memory

give_up_on_memory_tracking()

store(addr, val)

load(addr)

get(reg)

put(reg, val)

copy()

freeze()

merge(other)

exception angr.analyses.stack_pointer_tracker.CouldNotResolveException

Bases: Exception

An exception used in StackPointerTracker analysis to represent internal resolving failures.

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class angr.analyses.stack_pointer_tracker.StackPointerTracker(func, reg_offsets, block=None, track_memory=True)

Bases: Analysis, ForwardAnalysis

Track the offset of stack pointer at the end of each basic block of a function.

__init__(func, reg_offsets, block=None, track_memory=True)

Parameters:

• func (Function | None) –

• reg_offsets (Set[int]) –

• block (Block | None) –

offset_after(addr, reg)

offset_before(addr, reg)

offset_after_block(block_addr, reg)

offset_before_block(block_addr, reg)

property inconsistent

inconsistent_for(reg)

abort()

Abort the analysis :return: None

downsize()

errors = []

property graph: DiGraph

has_job(job)

Checks whether there exists another job which has the same job key. :type job: TypeVar(JobType) :param job: The job to check.

Return type:

bool

Returns:

True if there exists another job with the same key, False otherwise.

Parameters:

job (JobType) –

property jobs

named_errors = {}

property should_abort

Should the analysis be terminated. :return: True/False

project: Project

kb: KnowledgeBase

class angr.analyses.variable_recovery.annotations.StackLocationAnnotation(offset)

Bases: Annotation

__init__(offset)

property eliminatable

Returns whether this annotation can be eliminated in a simplification.

Returns:

True if eliminatable, False otherwise

property relocatable

Returns whether this annotation can be relocated in a simplification.

Returns:

True if it can be relocated, false otherwise.

relocate(src, dst)

This is called when an annotation has to be relocated because of simplifications.

Consider the following case:

x = claripy.BVS(‘x’, 32) zero = claripy.BVV(0, 32).add_annotation(your_annotation) y = x + zero

Here, one of three things can happen:

1. if your_annotation.eliminatable is True, the simplifiers will simply eliminate your_annotation along with zero and y is x will hold

2. elif your_annotation.relocatable is False, the simplifier will abort and y will never be simplified

3. elif your_annotation.relocatable is True, the simplifier will run, determine that the simplified result of x + zero will be x. It will then call your_annotation.relocate(zero, x) to move the annotation away from the AST that is about to be eliminated.

Parameters:

• src – the old AST that was eliminated in the simplification

• dst – the new AST (the result of a simplification)

Returns:

the annotation that will be applied to dst

class angr.analyses.variable_recovery.annotations.VariableSourceAnnotation(block_addr, stmt_idx, ins_addr)

Bases: Annotation

__init__(block_addr, stmt_idx, ins_addr)

property eliminatable

Returns whether this annotation can be eliminated in a simplification.

Returns:

True if eliminatable, False otherwise

property relocatable

Returns whether this annotation can be relocated in a simplification.

Returns:

True if it can be relocated, false otherwise.

static from_state(state)

relocate(src, dst)

This is called when an annotation has to be relocated because of simplifications.

Consider the following case:

x = claripy.BVS(‘x’, 32) zero = claripy.BVV(0, 32).add_annotation(your_annotation) y = x + zero

Here, one of three things can happen:

1. if your_annotation.eliminatable is True, the simplifiers will simply eliminate your_annotation along with zero and y is x will hold

2. elif your_annotation.relocatable is False, the simplifier will abort and y will never be simplified

3. elif your_annotation.relocatable is True, the simplifier will run, determine that the simplified result of x + zero will be x. It will then call your_annotation.relocate(zero, x) to move the annotation away from the AST that is about to be eliminated.

Parameters:

• src – the old AST that was eliminated in the simplification

• dst – the new AST (the result of a simplification)

Returns:

the annotation that will be applied to dst

angr.analyses.variable_recovery.variable_recovery_base.parse_stack_pointer(sp)

Convert multiple supported forms of stack pointer representations into stack offsets.

Parameters:

sp – A stack pointer representation.

Returns:

A stack pointer offset.

Return type:

int

class angr.analyses.variable_recovery.variable_recovery_base.VariableAnnotation(addr_and_variables)

Bases: Annotation

Parameters:

addr_and_variables (List[Tuple[int, SimVariable]]) –

__init__(addr_and_variables)

Parameters:

addr_and_variables (List[Tuple[int, SimVariable]]) –

addr_and_variables

property relocatable

Returns whether this annotation can be relocated in a simplification.

Returns:

True if it can be relocated, false otherwise.

property eliminatable

Returns whether this annotation can be eliminated in a simplification.

Returns:

True if eliminatable, False otherwise

relocate(src, dst)

This is called when an annotation has to be relocated because of simplifications.

Consider the following case:

x = claripy.BVS(‘x’, 32) zero = claripy.BVV(0, 32).add_annotation(your_annotation) y = x + zero

Here, one of three things can happen:

1. if your_annotation.eliminatable is True, the simplifiers will simply eliminate your_annotation along with zero and y is x will hold

2. elif your_annotation.relocatable is False, the simplifier will abort and y will never be simplified

3. elif your_annotation.relocatable is True, the simplifier will run, determine that the simplified result of x + zero will be x. It will then call your_annotation.relocate(zero, x) to move the annotation away from the AST that is about to be eliminated.

Parameters:

• src – the old AST that was eliminated in the simplification

• dst – the new AST (the result of a simplification)

Returns:

the annotation that will be applied to dst

class angr.analyses.variable_recovery.variable_recovery_base.VariableRecoveryBase(func, max_iterations, store_live_variables)

Bases: Analysis

The base class for VariableRecovery and VariableRecoveryFast.

Parameters:

store_live_variables (bool) –

__init__(func, max_iterations, store_live_variables)

Parameters:

store_live_variables (bool) –

get_variable_definitions(block_addr)

Get variables that are defined at the specified block.

Parameters:

block_addr (int) – Address of the block.

Returns:

A set of variables.

initialize_dominance_frontiers()

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

class angr.analyses.variable_recovery.variable_recovery_base.VariableRecoveryStateBase(block_addr, analysis, arch, func, stack_region=None, register_region=None, global_region=None, typevars=None, type_constraints=None, delayed_type_constraints=None, stack_offset_typevars=None, project=None)

Bases: object

The base abstract state for variable recovery analysis.

__init__(block_addr, analysis, arch, func, stack_region=None, register_region=None, global_region=None, typevars=None, type_constraints=None, delayed_type_constraints=None, stack_offset_typevars=None, project=None)

static top(bits)

Return type:

BV

static is_top(thing)

Return type:

bool

static extract_variables(expr)

Return type:

Generator[Tuple[int, Union[SimVariable, SpOffset]], None, None]

Parameters:

expr (Base) –

static annotate_with_variables(expr, addr_and_variables)

Return type:

Base

Parameters:

• expr (Base) –

• addr_and_variables (Iterable[Tuple[int, SimVariable | SpOffset]]) –

stack_address(offset)

Return type:

Base

Parameters:

offset (int) –

static is_stack_address(addr)

Return type:

bool

Parameters:

addr (Base) –

is_global_variable_address(addr)

Return type:

bool

Parameters:

addr (Base) –

static extract_stack_offset_from_addr(addr)

Return type:

Base

Parameters:

addr (Base) –

get_stack_offset(addr)

Return type:

Optional[int]

Parameters:

addr (Base) –

stack_addr_from_offset(offset)

Return type:

int

Parameters:

offset (int) –

property func_addr

property dominance_frontiers

property variable_manager

property variables

get_variable_definitions(block_addr)

Get variables that are defined at the specified block.

Parameters:

block_addr (int) – Address of the block.

Returns:

A set of variables.

add_type_constraint(constraint)

Add a new type constraint.

Parameters:

constraint –

Returns:

downsize()

Remove unnecessary members.

Return type:

None

Returns:

None

static downsize_region(region)

Get rid of unnecessary references in region so that it won’t avoid garbage collection on those referenced objects.

Parameters:

region (MultiValuedMemory) – A MultiValuedMemory region.

Return type:

MultiValuedMemory

Returns:

None

class angr.analyses.variable_recovery.variable_recovery_fast.VariableRecoveryFastState(block_addr, analysis, arch, func, stack_region=None, register_region=None, global_region=None, typevars=None, type_constraints=None, delayed_type_constraints=None, stack_offset_typevars=None, project=None, ret_val_size=None)

Bases: VariableRecoveryStateBase

The abstract state of variable recovery analysis.

Variables:

• stack_region (KeyedRegion) – The stack store.

• register_region (KeyedRegion) – The register store.

__init__(block_addr, analysis, arch, func, stack_region=None, register_region=None, global_region=None, typevars=None, type_constraints=None, delayed_type_constraints=None, stack_offset_typevars=None, project=None, ret_val_size=None)

copy()

merge(others, successor=None)

Merge two abstract states.

For any node A whose dominance frontier that the current node (at the current program location) belongs to, we create a phi variable V’ for each variable V that is defined in A, and then replace all existence of V with V’ in the merged abstract state.

Parameters:

others (Tuple[VariableRecoveryFastState]) – Other abstract states to merge.

Return type:

Tuple[VariableRecoveryFastState, bool]

Returns:

The merged abstract state.

add_type_constraint(constraint)

Add a new type constraint.

Parameters:

constraint –

Returns:

static annotate_with_variables(expr, addr_and_variables)

Return type:

Base

Parameters:

• expr (Base) –

• addr_and_variables (Iterable[Tuple[int, SimVariable | SpOffset]]) –

property dominance_frontiers

downsize()

Remove unnecessary members.

Return type:

None

Returns:

None

static downsize_region(region)

Get rid of unnecessary references in region so that it won’t avoid garbage collection on those referenced objects.

Parameters:

region (MultiValuedMemory) – A MultiValuedMemory region.

Return type:

MultiValuedMemory

Returns:

None

static extract_stack_offset_from_addr(addr)

Return type:

Base

Parameters:

addr (Base) –

static extract_variables(expr)

Return type:

Generator[Tuple[int, Union[SimVariable, SpOffset]], None, None]

Parameters:

expr (Base) –

property func_addr

get_stack_offset(addr)

Return type:

Optional[int]

Parameters:

addr (Base) –

get_variable_definitions(block_addr)

Get variables that are defined at the specified block.

Parameters:

block_addr (int) – Address of the block.

Returns:

A set of variables.

is_global_variable_address(addr)

Return type:

bool

Parameters:

addr (Base) –

static is_stack_address(addr)

Return type:

bool

Parameters:

addr (Base) –

static is_top(thing)

Return type:

bool

stack_addr_from_offset(offset)

Return type:

int

Parameters:

offset (int) –

stack_address(offset)

Return type:

Base

Parameters:

offset (int) –

static top(bits)

Return type:

BV

property variable_manager

property variables

class angr.analyses.variable_recovery.variable_recovery_fast.VariableRecoveryFast(func, func_graph=None, max_iterations=2, low_priority=False, track_sp=True, func_args=None, store_live_variables=False)

Bases: ForwardAnalysis, VariableRecoveryBase

Recover “variables” from a function by keeping track of stack pointer offsets and pattern matching VEX statements.

If calling conventions are recovered prior to running VariableRecoveryFast, variables can be recognized more accurately. However, it is not a requirement. In this case, the function graph you pass must contain information indicating the call-out sites inside the analyzed function. These graph edges must be annotated with either "type": "call" or "outside": True.

__init__(func, func_graph=None, max_iterations=2, low_priority=False, track_sp=True, func_args=None, store_live_variables=False)

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.

• func (Function | str | int) –

• func_graph (DiGraph | None) –

• max_iterations (int) –

• func_args (List[SimVariable] | None) –

Returns:

None

abort()

Abort the analysis :return: None

downsize()

errors = []

get_variable_definitions(block_addr)

Get variables that are defined at the specified block.

Parameters:

block_addr (int) – Address of the block.

Returns:

A set of variables.

property graph: DiGraph

has_job(job)

Checks whether there exists another job which has the same job key. :type job: TypeVar(JobType) :param job: The job to check.

Return type:

bool

Returns:

True if there exists another job with the same key, False otherwise.

Parameters:

job (JobType) –

initialize_dominance_frontiers()

property jobs

named_errors = {}

property should_abort

Should the analysis be terminated. :return: True/False

project: Project

kb: KnowledgeBase

class angr.analyses.variable_recovery.variable_recovery.VariableRecoveryState(block_addr, analysis, arch, func, concrete_states, stack_region=None, register_region=None)

Bases: VariableRecoveryStateBase

The abstract state of variable recovery analysis.

Variables:

variable_manager (angr.knowledge.variable_manager.VariableManager) – The variable manager.

__init__(block_addr, analysis, arch, func, concrete_states, stack_region=None, register_region=None)

property concrete_states

get_concrete_state(addr)

Parameters:

addr –

Returns:

copy()

register_callbacks(concrete_states)

Parameters:

concrete_states –

Returns:

merge(others, successor=None)

Merge two abstract states.

Parameters:

others (Tuple[VariableRecoveryState]) – Other abstract states to merge.

Returns:

The merged abstract state.

Return type:

VariableRecoveryState, and a boolean that indicates if any merge has happened.

add_type_constraint(constraint)

Add a new type constraint.

Parameters:

constraint –

Returns:

static annotate_with_variables(expr, addr_and_variables)

Return type:

Base

Parameters:

• expr (Base) –

• addr_and_variables (Iterable[Tuple[int, SimVariable | SpOffset]]) –

property dominance_frontiers

downsize()

Remove unnecessary members.

Return type:

None

Returns:

None

static downsize_region(region)

Get rid of unnecessary references in region so that it won’t avoid garbage collection on those referenced objects.

Parameters:

region (MultiValuedMemory) – A MultiValuedMemory region.

Return type:

MultiValuedMemory

Returns:

None

static extract_stack_offset_from_addr(addr)

Return type:

Base

Parameters:

addr (Base) –

static extract_variables(expr)

Return type:

Generator[Tuple[int, Union[SimVariable, SpOffset]], None, None]

Parameters:

expr (Base) –

property func_addr

get_stack_offset(addr)

Return type:

Optional[int]

Parameters:

addr (Base) –

get_variable_definitions(block_addr)

Get variables that are defined at the specified block.

Parameters:

block_addr (int) – Address of the block.

Returns:

A set of variables.

is_global_variable_address(addr)

Return type:

bool

Parameters:

addr (Base) –

static is_stack_address(addr)

Return type:

bool

Parameters:

addr (Base) –

static is_top(thing)

Return type:

bool

stack_addr_from_offset(offset)

Return type:

int

Parameters:

offset (int) –

stack_address(offset)

Return type:

Base

Parameters:

offset (int) –

static top(bits)

Return type:

BV

property variable_manager

property variables

class angr.analyses.variable_recovery.variable_recovery.VariableRecovery(func, max_iterations=20, store_live_variables=False)

Bases: ForwardAnalysis, VariableRecoveryBase

Recover “variables” from a function using forced execution.

While variables play a very important role in programming, it does not really exist after compiling. However, we can still identify and recovery their counterparts in binaries. It is worth noting that not every variable in source code can be identified in binaries, and not every recognized variable in binaries have a corresponding variable in the original source code. In short, there is no guarantee that the variables we identified/recognized in a binary are the same variables in its source code.

This analysis uses heuristics to identify and recovers the following types of variables: - Register variables. - Stack variables. - Heap variables. (not implemented yet) - Global variables. (not implemented yet)

This analysis takes a function as input, and performs a data-flow analysis on nodes. It runs concrete execution on every statement and hooks all register/memory accesses to discover all places that are accessing variables. It is slow, but has a more accurate analysis result. For a fast but inaccurate variable recovery, you may consider using VariableRecoveryFast.

This analysis follows SSA, which means every write creates a new variable in registers or memory (statck, heap, etc.). Things may get tricky when overlapping variable (in memory, as you cannot really have overlapping accesses to registers) accesses exist, and in such cases, a new variable will be created, and this new variable will overlap with one or more existing varaibles. A decision procedure (which is pretty much TODO) is required at the end of this analysis to resolve the conflicts between overlapping variables.

__init__(func, max_iterations=20, store_live_variables=False)

Parameters:

func (knowledge.Function) – The function to analyze.

abort()

Abort the analysis :return: None

downsize()

errors = []

get_variable_definitions(block_addr)

Get variables that are defined at the specified block.

Parameters:

block_addr (int) – Address of the block.

Returns:

A set of variables.

property graph: DiGraph

has_job(job)

Checks whether there exists another job which has the same job key. :type job: TypeVar(JobType) :param job: The job to check.

Return type:

bool

Returns:

True if there exists another job with the same key, False otherwise.

Parameters:

job (JobType) –

initialize_dominance_frontiers()

property jobs

named_errors = {}

property should_abort

Should the analysis be terminated. :return: True/False

project: Project

kb: KnowledgeBase

class angr.analyses.variable_recovery.engine_ail.SimEngineVRAIL(*args, call_info=None, **kwargs)

Bases: SimEngineLightAILMixin, SimEngineVRBase

The engine for variable recovery on AIL.

state: VariableRecoveryFastState

block: Block

__init__(*args, call_info=None, **kwargs)

static extract_offset_to_sp(spoffset_expr)

Extract the offset to the original stack pointer.

Parameters:

spoffset_expr (Base) – The claripy AST to parse.

Return type:

Optional[int]

Returns:

The offset to the original stack pointer, or None if spoffset_expr is not a supported type of SpOffset expression.

property func_addr

process(state, *args, **kwargs)

The main entry point for an engine. Should take a state and return a result.

Parameters:

state – The state to proceed from

Returns:

The result. Whatever you want ;)

static sp_offset(bits, offset)

Parameters:

• bits (int) –

• offset (int) –

class angr.analyses.variable_recovery.engine_vex.SimEngineVRVEX(*args, call_info=None, **kwargs)

Bases: SimEngineLightVEXMixin, SimEngineVRBase

Implements the VEX engine for variable recovery analysis.

state: VariableRecoveryStateBase

__init__(*args, call_info=None, **kwargs)

static extract_offset_to_sp(spoffset_expr)

Extract the offset to the original stack pointer.

Parameters:

spoffset_expr (Base) – The claripy AST to parse.

Return type:

Optional[int]

Returns:

The offset to the original stack pointer, or None if spoffset_expr is not a supported type of SpOffset expression.

property func_addr

process(state, *args, **kwargs)

The main entry point for an engine. Should take a state and return a result.

Parameters:

state – The state to proceed from

Returns:

The result. Whatever you want ;)

static sp_offset(bits, offset)

Parameters:

• bits (int) –

• offset (int) –

class angr.analyses.variable_recovery.engine_base.RichR(data, variable=None, typevar=None, type_constraints=None)

Bases: object

A rich representation of calculation results. The variable recovery data domain.

Parameters:

• data (Base) –

• typevar (TypeVariable | None) –

__init__(data, variable=None, typevar=None, type_constraints=None)

Parameters:

• data (Base) –

• typevar (TypeVariable | None) –

data: Base

variable

typevar

type_constraints

property bits

class angr.analyses.variable_recovery.engine_base.SimEngineVRBase(project, kb)

Bases: SimEngineLight

The base class for variable recovery analyses. Contains methods for basic interactions with the state, like loading and storing data.

state: VariableRecoveryStateBase

__init__(project, kb)

property func_addr

process(state, *args, **kwargs)

The main entry point for an engine. Should take a state and return a result.

Parameters:

state – The state to proceed from

Returns:

The result. Whatever you want ;)

static extract_offset_to_sp(spoffset_expr)

Extract the offset to the original stack pointer.

Parameters:

spoffset_expr (Base) – The claripy AST to parse.

Return type:

Optional[int]

Returns:

The offset to the original stack pointer, or None if spoffset_expr is not a supported type of SpOffset expression.

static sp_offset(bits, offset)

Parameters:

• bits (int) –

• offset (int) –

class angr.analyses.variable_recovery.irsb_scanner.VEXIRSBScanner(*args, **kwargs)

Bases: SimEngineLightVEXMixin

Scan the VEX IRSB to determine if any argument-passing registers should be narrowed by detecting cases of loading the whole register and immediately narrowing the register before writing to the tmp.

__init__(*args, **kwargs)

static extract_offset_to_sp(spoffset_expr)

Extract the offset to the original stack pointer.

Parameters:

spoffset_expr (Base) – The claripy AST to parse.

Return type:

Optional[int]

Returns:

The offset to the original stack pointer, or None if spoffset_expr is not a supported type of SpOffset expression.

static sp_offset(bits, offset)

Parameters:

• bits (int) –

• offset (int) –

class angr.analyses.typehoon.lifter.TypeLifter(bits)

Bases: object

Lift SimTypes to type constants.

Parameters:

bits (int) –

__init__(bits)

Parameters:

bits (int) –

bits

lift(ty)

Parameters:

ty (SimType) –

class angr.analyses.typehoon.simple_solver.RecursiveType(typevar, offset)

Bases: object

__init__(typevar, offset)

class angr.analyses.typehoon.simple_solver.SimpleSolver(bits, constraints)

Bases: object

SimpleSolver is, literally, a simple, unification-based type constraint solver.

Parameters:

bits (int) –

__init__(bits, constraints)

Parameters:

bits (int) –

solve()

determine()

class angr.analyses.typehoon.translator.SimTypeTempRef(typevar)

Bases: SimType

__init__(typevar)

Parameters:

label – the type label.

c_repr()

property alignment

The alignment of the type in bytes.

base = True

copy()

extract_claripy(bits)

Given a bitvector bits which was loaded from memory in a big-endian fashion, return a more appropriate or structured representation of the data.

A type must have an arch associated in order to use this method.

property size

The size of the type in bits.

with_arch(arch)

class angr.analyses.typehoon.translator.TypeTranslator(arch=None)

Bases: object

Translate type variables to SimType equivalence.

__init__(arch=None)

struct_name()

tc2simtype(tc)

simtype2tc(simtype)

Return type:

TypeConstant

Parameters:

simtype (SimType) –

backpatch(st, translated)

Parameters:

• st (sim_type.SimType) –

• translated (dict) –

Returns:

class angr.analyses.typehoon.typevars.TypeConstraint

Bases: object

pp_str(mapping)

Return type:

str

Parameters:

mapping (Dict[TypeVariable, Any]) –

class angr.analyses.typehoon.typevars.Equivalence(type_a, type_b)

Bases: TypeConstraint

__init__(type_a, type_b)

type_a

type_b

pp_str(mapping)

Return type:

str

Parameters:

mapping (Dict[TypeVariable, Any]) –

class angr.analyses.typehoon.typevars.Existence(type_)

Bases: TypeConstraint

__init__(type_)

type_

pp_str(mapping)

Return type:

str

Parameters:

mapping (Dict[TypeVariable, Any]) –

replace(replacements)

class angr.analyses.typehoon.typevars.Subtype(sub_type, super_type)

Bases: TypeConstraint

__init__(sub_type, super_type)

super_type

sub_type

pp_str(mapping)

Return type:

str

Parameters:

mapping (Dict[TypeVariable, Any]) –

replace(replacements)

class angr.analyses.typehoon.typevars.Add(type_0, type_1, type_r)

Bases: TypeConstraint

Describes the constraint that type_r == type0 + type1

__init__(type_0, type_1, type_r)

type_0

type_1

type_r

pp_str(mapping)

Return type:

str

Parameters:

mapping (Dict[TypeVariable, Any]) –

replace(replacements)

class angr.analyses.typehoon.typevars.Sub(type_0, type_1, type_r)

Bases: TypeConstraint

Describes the constraint that type_r == type0 - type1

__init__(type_0, type_1, type_r)

type_0

type_1

type_r

pp_str(mapping)

Return type:

str

Parameters:

mapping (Dict[TypeVariable, Any]) –

replace(replacements)

class angr.analyses.typehoon.typevars.TypeVariable(idx=None)

Bases: object

Parameters:

idx (int | None) –

__init__(idx=None)

Parameters:

idx (int | None) –

idx: int

pp_str(mapping)

Return type:

str

Parameters:

mapping (Dict[TypeVariable, Any]) –

class angr.analyses.typehoon.typevars.DerivedTypeVariable(type_var, label, idx=None)

Bases: TypeVariable

Parameters:

idx (int) –

__init__(type_var, label, idx=None)

type_var

label

pp_str(mapping)

Return type:

str

Parameters:

mapping (Dict[TypeVariable, Any]) –

replace(replacements)

idx: int

class angr.analyses.typehoon.typevars.TypeVariables

Bases: object

__init__()

merge(tvs)

copy()

add_type_variable(var, codeloc, typevar)

Parameters:

• var (SimVariable) –

• typevar (TypeVariable) –

get_type_variable(var, codeloc)

has_type_variable_for(var, codeloc)

Parameters:

var (SimVariable) –

class angr.analyses.typehoon.typevars.BaseLabel

Bases: object

class angr.analyses.typehoon.typevars.FuncIn(loc)

Bases: BaseLabel

__init__(loc)

loc

class angr.analyses.typehoon.typevars.FuncOut(loc)

Bases: BaseLabel

__init__(loc)

loc

class angr.analyses.typehoon.typevars.Load

Bases: BaseLabel

class angr.analyses.typehoon.typevars.Store

Bases: BaseLabel

class angr.analyses.typehoon.typevars.AddN(n)

Bases: BaseLabel

__init__(n)

n

class angr.analyses.typehoon.typevars.SubN(n)

Bases: BaseLabel

__init__(n)

n

class angr.analyses.typehoon.typevars.ConvertTo(to_bits)

Bases: BaseLabel

__init__(to_bits)

to_bits

class angr.analyses.typehoon.typevars.ReinterpretAs(to_type, to_bits)

Bases: BaseLabel

__init__(to_type, to_bits)

to_type

to_bits

class angr.analyses.typehoon.typevars.HasField(bits, offset)

Bases: BaseLabel

__init__(bits, offset)

bits

offset

class angr.analyses.typehoon.typevars.IsArray

Bases: BaseLabel

class angr.analyses.typehoon.typehoon.Typehoon(constraints, ground_truth=None, var_mapping=None, must_struct=None)

Bases: Analysis

A spiritual tribute to the long-standing typehoon project that @jmg (John Grosen) worked on during his days in the angr team. Now I feel really bad of asking the poor guy to work directly on VEX IR without any fancy static analysis support as we have right now…

Typehoon analysis implements a pushdown system that simplifies and solves type constraints. Our type constraints are largely an implementation of the paper Polymorphic Type Inference for Machine Code by Noonan, Loginov, and Cok from GrammaTech (with missing functionality support and bugs, of course). Type constraints are collected by running VariableRecoveryFast (maybe VariableRecovery later as well) on a function, and then solved using this analysis.

User may specify ground truth, which will override all types at certain program points during constraint solving.

Parameters:

• var_mapping (Dict[SimVariable, Set[TypeVariable]] | None) –

• must_struct (Set[TypeVariable] | None) –

__init__(constraints, ground_truth=None, var_mapping=None, must_struct=None)

Parameters:

• constraints –

• ground_truth – A set of SimType-style solutions for some or all type variables. They will be respected during type solving.

• var_mapping (Optional[Dict[SimVariable, Set[TypeVariable]]]) –

• must_struct (Optional[Set[TypeVariable]]) –

update_variable_types(func_addr, var_to_typevars)

Parameters:

func_addr (int | str) –

pp_constraints()

Pretty-print constraints between variables using the variable mapping.

Return type:

None

pp_solution()

Pretty-print solutions using the variable mapping.

Return type:

None

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

All type constants used in type inference. They can be mapped, translated, or rewritten to C-style types.

class angr.analyses.typehoon.typeconsts.TypeConstant

Bases: object

SIZE = None

pp_str(mapping)

Return type:

str

property size: int

class angr.analyses.typehoon.typeconsts.TopType

Bases: TypeConstant

SIZE = None

pp_str(mapping)

Return type:

str

property size: int

class angr.analyses.typehoon.typeconsts.BottomType

Bases: TypeConstant

SIZE = None

pp_str(mapping)

Return type:

str

property size: int

class angr.analyses.typehoon.typeconsts.Int

Bases: TypeConstant

SIZE = None

pp_str(mapping)

Return type:

str

property size: int

class angr.analyses.typehoon.typeconsts.Int1

Bases: Int

SIZE = 1

pp_str(mapping)

Return type:

str

property size: int

class angr.analyses.typehoon.typeconsts.Int8

Bases: Int

SIZE = 1

pp_str(mapping)

Return type:

str

property size: int

class angr.analyses.typehoon.typeconsts.Int16

Bases: Int

SIZE = 2

pp_str(mapping)

Return type:

str

property size: int

class angr.analyses.typehoon.typeconsts.Int32

Bases: Int

SIZE = 4

pp_str(mapping)

Return type:

str

property size: int

class angr.analyses.typehoon.typeconsts.Int64

Bases: Int

SIZE = 8

pp_str(mapping)

Return type:

str

property size: int

class angr.analyses.typehoon.typeconsts.Int128

Bases: Int

SIZE = 16

pp_str(mapping)

Return type:

str

property size: int

class angr.analyses.typehoon.typeconsts.FloatBase

Bases: TypeConstant

SIZE = None

pp_str(mapping)

Return type:

str

property size: int

class angr.analyses.typehoon.typeconsts.Float

Bases: FloatBase

SIZE = 4

pp_str(mapping)

Return type:

str

property size: int

class angr.analyses.typehoon.typeconsts.Double

Bases: FloatBase

SIZE = 8

pp_str(mapping)

Return type:

str

property size: int

class angr.analyses.typehoon.typeconsts.Pointer(basetype)

Bases: TypeConstant

__init__(basetype)

new(basetype)

SIZE = None

pp_str(mapping)

Return type:

str

property size: int

class angr.analyses.typehoon.typeconsts.Pointer32(basetype)

Bases: Pointer, Int32

32-bit pointers.

__init__(basetype)

SIZE = 4

new(basetype)

pp_str(mapping)

Return type:

str

property size: int

class angr.analyses.typehoon.typeconsts.Pointer64(basetype)

Bases: Pointer, Int64

64-bit pointers.

__init__(basetype)

SIZE = 8

new(basetype)

pp_str(mapping)

Return type:

str

property size: int

class angr.analyses.typehoon.typeconsts.Array(element, count=None)

Bases: TypeConstant

__init__(element, count=None)

SIZE = None

pp_str(mapping)

Return type:

str

property size: int

class angr.analyses.typehoon.typeconsts.Struct(fields=None)

Bases: TypeConstant

__init__(fields=None)

SIZE = None

pp_str(mapping)

Return type:

str

property size: int

class angr.analyses.typehoon.typeconsts.TypeVariableReference(typevar)

Bases: TypeConstant

__init__(typevar)

SIZE = None

pp_str(mapping)

Return type:

str

property size: int

angr.analyses.typehoon.typeconsts.int_type(bits)

Return type:

Optional[Int]

Parameters:

bits (int) –

angr.analyses.typehoon.typeconsts.float_type(bits)

Return type:

Optional[FloatBase]

Parameters:

bits (int) –

class angr.analyses.identifier.identify.FuncInfo

Bases: object

__init__()

class angr.analyses.identifier.identify.Identifier(cfg=None, require_predecessors=True, only_find=None)

Bases: Analysis

__init__(cfg=None, require_predecessors=True, only_find=None)

run(only_find=None)

can_call_same_name(addr, name)

get_func_info(func)

static constrain_all_zero(before_state, state, regs)

identify_func(function)

check_tests(cfg_func, match_func)

map_callsites()

do_trace(addr_trace, reverse_accesses, func_info)

get_call_args(func, callsite)

static get_reg_name(arch, reg_offset)

Parameters:

• arch – the architecture

• reg_offset – Tries to find the name of a register given the offset in the registers.

Returns:

The register name

find_stack_vars_x86(func)

static make_initial_state(project, stack_length)

Returns:

an initial state with a symbolic stack and good options for rop

errors = []

static make_symbolic_state(project, reg_list, stack_length=80)

converts an input state into a state with symbolic registers :return: the symbolic state

named_errors = {}

project: Project

kb: KnowledgeBase

class angr.analyses.loopfinder.Loop(entry, entry_edges, break_edges, continue_edges, body_nodes, graph, subloops)

Bases: object

__init__(entry, entry_edges, break_edges, continue_edges, body_nodes, graph, subloops)

class angr.analyses.loopfinder.LoopFinder(functions=None, normalize=True)

Bases: Analysis

Extracts all the loops from all the functions in a binary.

__init__(functions=None, normalize=True)

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

class angr.analyses.loop_analysis.VariableTypes

Bases: object

Iterator = 'Iterator'

HasNext = 'HasNext'

Next = 'Next'

class angr.analyses.loop_analysis.AnnotatedVariable(variable, type_)

Bases: object

__init__(variable, type_)

variable

type

class angr.analyses.loop_analysis.Condition(op, val0, val1)

Bases: object

Equal = '=='

NotEqual = '!='

__init__(op, val0, val1)

classmethod from_opstr(opstr)

class angr.analyses.loop_analysis.SootBlockProcessor(state, block, loop, defuse)

Bases: object

__init__(state, block, loop, defuse)

process()

class angr.analyses.loop_analysis.LoopAnalysisState(block)

Bases: object

__init__(block)

copy()

merge(state)

add_loop_exit_stmt(stmt_idx, condition=None)

class angr.analyses.loop_analysis.LoopAnalysis(loop, defuse)

Bases: ForwardAnalysis, Analysis

Analyze a loop and recover important information about the loop (e.g., invariants, induction variables) in a static manner.

__init__(loop, defuse)

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

abort()

Abort the analysis :return: None

downsize()

errors = []

property graph: DiGraph

has_job(job)

Checks whether there exists another job which has the same job key. :type job: TypeVar(JobType) :param job: The job to check.

Return type:

bool

Returns:

True if there exists another job with the same key, False otherwise.

Parameters:

job (JobType) –

property jobs

named_errors = {}

property should_abort

Should the analysis be terminated. :return: True/False

project: Project

kb: KnowledgeBase

exception angr.analyses.veritesting.VeritestingError

Bases: Exception

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class angr.analyses.veritesting.CallTracingFilter(project, depth, blacklist=None)

Bases: object

Filter to apply during CFG creation on a given state and jumpkind to determine if it should be skipped at a certain depth

whitelist = {<class 'angr.procedures.libc.fgetc.fgetc'>, <class 'angr.procedures.glibc.__ctype_b_loc.__ctype_b_loc'>, <class 'angr.procedures.cgc.receive.receive'>, <class 'angr.procedures.cgc.transmit.transmit'>, <class 'angr.procedures.posix.read.read'>, <class 'angr.procedures.libc.strlen.strlen'>, <class 'angr.procedures.libc.strcmp.strcmp'>, <class 'angr.procedures.libc.atoi.atoi'>}

cfg_cache = {}

__init__(project, depth, blacklist=None)

filter(call_target_state, jumpkind)

The call will be skipped if it returns True.

Parameters:

• call_target_state – The new state of the call target.

• jumpkind – The Jumpkind of this call.

Returns:

True if we want to skip this call, False otherwise.

class angr.analyses.veritesting.Veritesting(input_state, boundaries=None, loop_unrolling_limit=10, enable_function_inlining=False, terminator=None, deviation_filter=None)

Bases: Analysis

An exploration technique made for condensing chunks of code to single (nested) if-then-else constraints via CFG accurate to conduct Static Symbolic Execution SSE (conversion to single constraint)

cfg_cache = {}

all_stashes = ('successful', 'errored', 'deadended', 'deviated', 'unconstrained')

__init__(input_state, boundaries=None, loop_unrolling_limit=10, enable_function_inlining=False, terminator=None, deviation_filter=None)

SSE stands for Static Symbolic Execution, and we also implemented an extended version of Veritesting (Avgerinos, Thanassis, et al, ICSE 2014).

Parameters:

• input_state – The initial state to begin the execution with.

• boundaries – Addresses where execution should stop.

• loop_unrolling_limit – The maximum times that Veritesting should unroll a loop for.

• enable_function_inlining – Whether we should enable function inlining and syscall inlining.

• terminator – A callback function that takes a state as parameter. Veritesting will terminate if this function returns True.

• deviation_filter – A callback function that takes a state as parameter. Veritesting will put the state into “deviated” stash if this function returns True.

is_not_in_cfg(s)

Returns if s.addr is not a proper node in our CFG.

Parameters:

s (SimState) – The SimState instance to test.

Returns bool:

False if our CFG contains p.addr, True otherwise.

is_overbound(state)

Filter out all states that run out of boundaries or loop too many times.

param SimState state: SimState instance to check returns bool: True if outside of mem/loop_ctr boundary

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

class angr.analyses.vfg.VFGJob(*args, **kwargs)

Bases: CFGJobBase

A job descriptor that contains local variables used during VFG analysis.

__init__(*args, **kwargs)

Return type:

None

property block_id: BlockID | None

callstack_repr(kb)

Parameters:

kb (KnowledgeBase) –

property call_stack

call_stack_copy()

property current_stack_pointer

property func_addr

get_call_stack_suffix()

class angr.analyses.vfg.PendingJob(block_id, state, call_stack, src_block_id, src_stmt_idx, src_ins_addr)

Bases: object

Describes a pending job during VFG analysis.

Parameters:

• block_id (BlockID) –

• state (SimState) –

• call_stack (CallStack) –

• src_block_id (BlockID) –

• src_stmt_idx (int) –

• src_ins_addr (int) –

__init__(block_id, state, call_stack, src_block_id, src_stmt_idx, src_ins_addr)

Parameters:

• block_id (BlockID) –

• state (SimState) –

• call_stack (CallStack) –

• src_block_id (BlockID) –

• src_stmt_idx (int) –

• src_ins_addr (int) –

Return type:

None

block_id

state

call_stack

src_block_id

src_stmt_idx

src_ins_addr

class angr.analyses.vfg.AnalysisTask

Bases: object

An analysis task describes a task that should be done before popping this task out of the task stack and discard it.

__init__()

Return type:

None

property done

class angr.analyses.vfg.FunctionAnalysis(function_address, return_address)

Bases: AnalysisTask

Analyze a function, generate fix-point states from all endpoints of that function, and then merge them to one state.

Parameters:

• function_address (int) –

• return_address (int | None) –

__init__(function_address, return_address)

Parameters:

• function_address (int) –

• return_address (int | None) –

Return type:

None

property done: bool

class angr.analyses.vfg.CallAnalysis(address, return_address, function_analysis_tasks=None, mergeable_plugins=None)

Bases: AnalysisTask

Analyze a call by analyze all functions this call might be calling, collect all final states generated by analyzing those functions, and merge them into one state.

Parameters:

• address (int) –

• return_address (None) –

• function_analysis_tasks (List[Any] | None) –

• mergeable_plugins (Tuple[str, str] | None) –

__init__(address, return_address, function_analysis_tasks=None, mergeable_plugins=None)

Parameters:

• address (int) –

• return_address (None) –

• function_analysis_tasks (List[Any] | None) –

• mergeable_plugins (Tuple[str, str] | None) –

Return type:

None

property done: bool

register_function_analysis(task)

Return type:

None

Parameters:

task (FunctionAnalysis) –

add_final_job(job)

Return type:

None

Parameters:

job (VFGJob) –

merge_jobs()

Return type:

VFGJob

class angr.analyses.vfg.VFGNode(addr, key, state=None)

Bases: object

A descriptor of nodes in a Value-Flow Graph

Parameters:

• addr (int) –

• key (BlockID) –

• state (SimState | None) –

__init__(addr, key, state=None)

Constructor.

Parameters:

• addr (int) –

• key (BlockID) –

• state (SimState) –

Return type:

None

append_state(s, is_widened_state=False)

Appended a new state to this VFGNode. :type s: :param s: The new state to append :type is_widened_state: :param is_widened_state: Whether it is a widened state or not.

class angr.analyses.vfg.VFG(cfg=None, context_sensitivity_level=2, start=None, function_start=None, interfunction_level=0, initial_state=None, avoid_runs=None, remove_options=None, timeout=None, max_iterations_before_widening=8, max_iterations=40, widening_interval=3, final_state_callback=None, status_callback=None, record_function_final_states=False)

Bases: ForwardAnalysis[SimState, VFGNode, VFGJob, BlockID], Analysis

This class represents a control-flow graph with static analysis result.

Perform abstract interpretation analysis starting from the given function address. The output is an invariant at the beginning (or the end) of each basic block.

Steps:

• Generate a CFG first if CFG is not provided.

• Identify all merge points (denote the set of merge points as Pw) in the CFG.

• Cut those loop back edges (can be derived from Pw) so that we gain an acyclic CFG.

• Identify all variables that are 1) from memory loading 2) from initial values, or 3) phi functions. Denote

  the set of those variables as S_{var}.

• Start real AI analysis and try to compute a fix point of each merge point. Perform widening/narrowing only on

  variables in S_{var}.

__init__(cfg=None, context_sensitivity_level=2, start=None, function_start=None, interfunction_level=0, initial_state=None, avoid_runs=None, remove_options=None, timeout=None, max_iterations_before_widening=8, max_iterations=40, widening_interval=3, final_state_callback=None, status_callback=None, record_function_final_states=False)

Parameters:

• cfg (Optional[CFGEmulated]) – The control-flow graph to base this analysis on. If none is provided, we will construct a CFGEmulated.

• context_sensitivity_level (int) – The level of context-sensitivity of this VFG. It ranges from 0 to infinity. Default 2.

• function_start (Optional[int]) – The address of the function to analyze.

• interfunction_level (int) – The level of interfunction-ness to be

• initial_state (Optional[SimState]) – A state to use as the initial one

• avoid_runs (Optional[List[int]]) – A list of runs to avoid

• remove_options (Optional[Set[str]]) – State options to remove from the initial state. It only works when initial_state is None

• timeout (int) –

• final_state_callback (Optional[Callable[[SimState, CallStack], Any]]) – callback function when countering final state

• status_callback (Optional[Callable[[VFG], Any]]) – callback function used in _analysis_core_baremetal

• start (int | None) –

• max_iterations_before_widening (int) –

• max_iterations (int) –

• widening_interval (int) –

• record_function_final_states (bool) –

Return type:

None

property function_initial_states

property function_final_states

get_any_node(addr)

Get any VFG node corresponding to the basic block at @addr. Note that depending on the context sensitivity level, there might be multiple nodes corresponding to different contexts. This function will return the first one it encounters, which might not be what you want.

Return type:

Optional[VFGNode]

Parameters:

addr (int) –

get_all_nodes(addr)

Return type:

Generator[VFGNode, None, None]

irsb_from_node(node)

copy()

abort()

Abort the analysis :return: None

downsize()

errors = []

property graph: DiGraph

has_job(job)

Checks whether there exists another job which has the same job key. :type job: TypeVar(JobType) :param job: The job to check.

Return type:

bool

Returns:

True if there exists another job with the same key, False otherwise.

Parameters:

job (JobType) –

property jobs

named_errors = {}

property should_abort

Should the analysis be terminated. :return: True/False

project: Project

kb: KnowledgeBase

class angr.analyses.vsa_ddg.DefUseChain(def_loc, use_loc, variable)

Bases: object

Stand for a def-use chain. it is generated by the DDG itself.

__init__(def_loc, use_loc, variable)

Constructor.

Parameters:

• def_loc –

• use_loc –

• variable –

Returns:

class angr.analyses.vsa_ddg.VSA_DDG(vfg=None, start_addr=None, interfunction_level=0, context_sensitivity_level=2, keep_data=False)

Bases: Analysis

A Data dependency graph based on VSA states. That means we don’t (and shouldn’t) expect any symbolic expressions.

__init__(vfg=None, start_addr=None, interfunction_level=0, context_sensitivity_level=2, keep_data=False)

Constructor.

Parameters:

• vfg – An already constructed VFG. If not specified, a new VFG will be created with other specified parameters. vfg and start_addr cannot both be unspecified.

• start_addr – The address where to start the analysis (typically, a function’s entry point).

• interfunction_level – See VFG analysis.

• context_sensitivity_level – See VFG analysis.

• keep_data – Whether we keep set of addresses as edges in the graph, or just the cardinality of the sets, which can be used as a “weight”.

get_predecessors(code_location)

Returns all predecessors of code_location.

Parameters:

code_location – A CodeLocation instance.

Returns:

A list of all predecessors.

get_all_nodes(simrun_addr, stmt_idx)

Get all DDG nodes matching the given basic block address and statement index.

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

class angr.analyses.vtable.Vtable(vaddr, size, func_addrs=None)

Bases: object

This contains the addr, size and function addresses of a Vtable

__init__(vaddr, size, func_addrs=None)

class angr.analyses.vtable.VtableFinder

Bases: Analysis

This analysis locates Vtables in a binary based on heuristics taken from - “Reconstruction of Class Hierarchies for Decompilation of C++ Programs”

__init__()

is_cross_referenced(addr)

is_function(addr)

analyze()

create_extract_vtable(start_addr, sec_size)

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

class angr.analyses.find_objects_static.PossibleObject(size, addr, class_name=None)

Bases: object

This holds the address and class name of possible class instances. The address that it holds in mapped outside the binary so it is only valid in this analysis. TO DO: map the address to its uses in the registers/memory locations in the instructions

__init__(size, addr, class_name=None)

class angr.analyses.find_objects_static.NewFunctionHandler(max_addr=None, new_func_addr=None, project=None)

Bases: FunctionHandler

This handles calls to the function new(), by recording the size parameter passed to it and also assigns a new

address outside the mapped binary to the newly created space(possible object).

It also tracks if the function called right after new() is passed the same ‘this’ pointer and is a constructor, if so we mark it as an instance of the class the constructor belongs to.(only for non stripped binaries)

__init__(max_addr=None, new_func_addr=None, project=None)

hook(analysis)

Attach this instance of the function handler to an instance of RDA.

handle_local_function(state, data)

Parameters:

• state (ReachingDefinitionsState) –

• data (FunctionCallData) –

static c_args_as_atoms(state, cc, prototype)

Return type:

List[Set[Atom]]

Parameters:

• state (ReachingDefinitionsState) –

• cc (SimCC) –

• prototype (SimTypeFunction) –

static c_return_as_atoms(state, cc, prototype)

Return type:

Set[Atom]

Parameters:

• state (ReachingDefinitionsState) –

• cc (SimCC) –

• prototype (SimTypeFunction) –

static caller_saved_regs_as_atoms(state, cc)

Return type:

Set[Register]

Parameters:

• state (ReachingDefinitionsState) –

• cc (SimCC) –

handle_external_function(state, data)

Parameters:

• state (ReachingDefinitionsState) –

• data (FunctionCallData) –

handle_function(state, data)

The main entry point for the function handler. Called with a RDA state and a FunctionCallData, it is expected to update the state and the data as per the contracts described on FunctionCallData.

You can override this method to take full control over how data is processed, or override any of the following to use the higher-level interface (data.depends()):

• handle_impl_<function name>

• handle_local_function

• handle_external_function

• handle_indirect_function

• handle_generic_function

Each of them take the same signature as handle_function.

Parameters:

• state (ReachingDefinitionsState) –

• data (FunctionCallData) –

handle_generic_function(state, data)

Parameters:

• state (ReachingDefinitionsState) –

• data (FunctionCallData) –

handle_indirect_function(state, data)

Parameters:

• state (ReachingDefinitionsState) –

• data (FunctionCallData) –

make_function_codeloc(target, callsite, callsite_func_addr)

The RDA engine will call this function to transform a callsite CodeLocation into a callee CodeLocation.

Parameters:

• target (None | int | MultiValues) –

• callsite (CodeLocation) –

• callsite_func_addr (int | None) –

static stack_pointer_as_atom(state)

Return type:

Register

class angr.analyses.find_objects_static.StaticObjectFinder

Bases: Analysis

This analysis tries to find objects on the heap based on calls to new(), and subsequent calls to constructors with

the ‘this’ pointer

__init__()

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

class angr.analyses.class_identifier.ClassIdentifier

Bases: Analysis

This is a class identifier for non stripped or partially stripped binaries, it identifies classes based on the demangled function names, and also assigns functions to their respective classes based on their names. It also uses the results from the VtableFinder analysis to assign the corresponding vtable to the classes.

self.classes contains a mapping between class names and SimCppClass objects

e.g. A::tool() and A::qux() belong to the class A

__init__()

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

class angr.analyses.disassembly.DisassemblyPiece

Bases: object

addr = None

ident = nan

render(formatting=None)

getpiece(formatting, column)

width(formatting)

height(formatting)

static color(string, coloring, formatting)

highlight(string, formatting=None)

class angr.analyses.disassembly.FunctionStart(func)

Bases: DisassemblyPiece

__init__(func)

Constructor.

Parameters:

func (angr.knowledge.Function) – The function instance.

addr = None

height(formatting)

static color(string, coloring, formatting)

getpiece(formatting, column)

highlight(string, formatting=None)

ident = nan

render(formatting=None)

width(formatting)

class angr.analyses.disassembly.Label(addr, name)

Bases: DisassemblyPiece

__init__(addr, name)

addr = None

static color(string, coloring, formatting)

getpiece(formatting, column)

height(formatting)

highlight(string, formatting=None)

ident = nan

render(formatting=None)

width(formatting)

class angr.analyses.disassembly.IROp(addr, seq, obj, irsb)

Bases: DisassemblyPiece

Parameters:

• addr (int) –

• seq (int) –

• obj (IRStmt | PcodeOp) –

• irsb (IRSB | IRSB) –

__init__(addr, seq, obj, irsb)

Parameters:

• addr (int) –

• seq (int) –

• obj (IRStmt | PcodeOp) –

• irsb (IRSB | IRSB) –

addr: int

seq: int

obj: Union[IRStmt, PcodeOp]

irsb: Union[IRSB, IRSB]

static color(string, coloring, formatting)

getpiece(formatting, column)

height(formatting)

highlight(string, formatting=None)

ident = nan

render(formatting=None)

width(formatting)

class angr.analyses.disassembly.BlockStart(block, parentfunc, project)

Bases: DisassemblyPiece

__init__(block, parentfunc, project)

addr = None

static color(string, coloring, formatting)

getpiece(formatting, column)

height(formatting)

highlight(string, formatting=None)

ident = nan

render(formatting=None)

width(formatting)

class angr.analyses.disassembly.Hook(block)

Bases: DisassemblyPiece

__init__(block)

addr = None

static color(string, coloring, formatting)

getpiece(formatting, column)

height(formatting)

highlight(string, formatting=None)

ident = nan

render(formatting=None)

width(formatting)

class angr.analyses.disassembly.Instruction(insn, parentblock, project=None)

Bases: DisassemblyPiece

__init__(insn, parentblock, project=None)

addr = None

property mnemonic

reload_format()

dissect_instruction()

dissect_instruction_for_arm()

static split_arm_op_string(op_str)

Parameters:

op_str (str) –

dissect_instruction_by_default()

static split_op_string(insn_str)

static color(string, coloring, formatting)

getpiece(formatting, column)

height(formatting)

highlight(string, formatting=None)

ident = nan

render(formatting=None)

width(formatting)

class angr.analyses.disassembly.SootExpression(expr)

Bases: DisassemblyPiece

__init__(expr)

addr = None

static color(string, coloring, formatting)

getpiece(formatting, column)

height(formatting)

highlight(string, formatting=None)

ident = nan

render(formatting=None)

width(formatting)

class angr.analyses.disassembly.SootExpressionTarget(target_stmt_idx)

Bases: SootExpression

__init__(target_stmt_idx)

addr = None

static color(string, coloring, formatting)

getpiece(formatting, column)

height(formatting)

highlight(string, formatting=None)

ident = nan

render(formatting=None)

width(formatting)

class angr.analyses.disassembly.SootExpressionStaticFieldRef(field)

Bases: SootExpression

__init__(field)

addr = None

static color(string, coloring, formatting)

getpiece(formatting, column)

height(formatting)

highlight(string, formatting=None)

ident = nan

render(formatting=None)

width(formatting)

class angr.analyses.disassembly.SootExpressionInvoke(invoke_type, expr)

Bases: SootExpression

Virtual = 'virtual'

Static = 'static'

Special = 'special'

__init__(invoke_type, expr)

addr = None

static color(string, coloring, formatting)

getpiece(formatting, column)

height(formatting)

highlight(string, formatting=None)

ident = nan

render(formatting=None)

width(formatting)

class angr.analyses.disassembly.SootStatement(block_addr, raw_stmt)

Bases: DisassemblyPiece

__init__(block_addr, raw_stmt)

addr = None

property stmt_idx

static color(string, coloring, formatting)

getpiece(formatting, column)

height(formatting)

highlight(string, formatting=None)

ident = nan

render(formatting=None)

width(formatting)

class angr.analyses.disassembly.Opcode(parentinsn)

Bases: DisassemblyPiece

__init__(parentinsn)

addr = None

ident = nan

static color(string, coloring, formatting)

getpiece(formatting, column)

height(formatting)

highlight(string, formatting=None)

render(formatting=None)

width(formatting)

class angr.analyses.disassembly.Operand(op_num, children, parentinsn)

Bases: DisassemblyPiece

__init__(op_num, children, parentinsn)

addr = None

ident = nan

property cs_operand

static build(operand_type, op_num, children, parentinsn)

static color(string, coloring, formatting)

getpiece(formatting, column)

height(formatting)

highlight(string, formatting=None)

render(formatting=None)

width(formatting)

class angr.analyses.disassembly.ConstantOperand(op_num, children, parentinsn)

Bases: Operand

__init__(op_num, children, parentinsn)

addr = None

static build(operand_type, op_num, children, parentinsn)

static color(string, coloring, formatting)

property cs_operand

getpiece(formatting, column)

height(formatting)

highlight(string, formatting=None)

ident = nan

render(formatting=None)

width(formatting)

class angr.analyses.disassembly.RegisterOperand(op_num, children, parentinsn)

Bases: Operand

property register

__init__(op_num, children, parentinsn)

addr = None

static build(operand_type, op_num, children, parentinsn)

static color(string, coloring, formatting)

property cs_operand

getpiece(formatting, column)

height(formatting)

highlight(string, formatting=None)

ident = nan

render(formatting=None)

width(formatting)

class angr.analyses.disassembly.MemoryOperand(op_num, children, parentinsn)

Bases: Operand

__init__(op_num, children, parentinsn)

addr = None

static build(operand_type, op_num, children, parentinsn)

static color(string, coloring, formatting)

property cs_operand

getpiece(formatting, column)

height(formatting)

highlight(string, formatting=None)

ident = nan

render(formatting=None)

width(formatting)

class angr.analyses.disassembly.OperandPiece

Bases: DisassemblyPiece

addr = None

parentop = None

ident = None

static color(string, coloring, formatting)

getpiece(formatting, column)

height(formatting)

highlight(string, formatting=None)

render(formatting=None)

width(formatting)

class angr.analyses.disassembly.Register(reg, prefix='')

Bases: OperandPiece

__init__(reg, prefix='')

addr = None

static color(string, coloring, formatting)

getpiece(formatting, column)

height(formatting)

highlight(string, formatting=None)

ident = None

parentop = None

render(formatting=None)

width(formatting)

class angr.analyses.disassembly.Value(val, render_with_sign)

Bases: OperandPiece

__init__(val, render_with_sign)

property project

addr = None

static color(string, coloring, formatting)

getpiece(formatting, column)

height(formatting)

highlight(string, formatting=None)

ident = None

parentop = None

render(formatting=None)

width(formatting)

class angr.analyses.disassembly.Comment(addr, text)

Bases: DisassemblyPiece

__init__(addr, text)

addr = None

height(formatting)

static color(string, coloring, formatting)

getpiece(formatting, column)

highlight(string, formatting=None)

ident = nan

render(formatting=None)

width(formatting)

class angr.analyses.disassembly.FuncComment(func)

Bases: DisassemblyPiece

__init__(func)

addr = None

static color(string, coloring, formatting)

getpiece(formatting, column)

height(formatting)

highlight(string, formatting=None)

ident = nan

render(formatting=None)

width(formatting)

class angr.analyses.disassembly.Disassembly(function=None, ranges=None, thumb=False, include_ir=False, block_bytes=None)

Bases: Analysis

Produce formatted machine code disassembly.

Parameters:

• function (Function | None) –

• ranges (Sequence[Tuple[int, int]] | None) –

• thumb (bool) –

• include_ir (bool) –

• block_bytes (bytes | None) –

__init__(function=None, ranges=None, thumb=False, include_ir=False, block_bytes=None)

Parameters:

• function (Function | None) –

• ranges (Sequence[Tuple[int, int]] | None) –

• thumb (bool) –

• include_ir (bool) –

• block_bytes (bytes | None) –

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

func_lookup(block)

parse_block(block)

Parse instructions for a given block node

Return type:

None

Parameters:

block (BlockNode) –

render(formatting=None, show_edges=True, show_addresses=True, show_bytes=False, ascii_only=None, color=True)

Render the disassembly to a string, with optional edges and addresses.

Color will be added by default, if enabled. To disable color pass an empty formatting dict.

Return type:

str

Parameters:

• show_edges (bool) –

• show_addresses (bool) –

• show_bytes (bool) –

• ascii_only (bool | None) –

• color (bool) –

angr.analyses.disassembly_utils.decode_instruction(arch, instr)

exception angr.analyses.reassembler.BinaryError

Bases: Exception

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.analyses.reassembler.InstructionError

Bases: BinaryError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.analyses.reassembler.ReassemblerFailureNotice

Bases: BinaryError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

angr.analyses.reassembler.string_escape(s)

angr.analyses.reassembler.fill_reg_map()

angr.analyses.reassembler.split_operands(s)

angr.analyses.reassembler.is_hex(s)

class angr.analyses.reassembler.Label(binary, name, original_addr=None)

Bases: object

g_label_ctr = count(0)

__init__(binary, name, original_addr=None)

property operand_str

property offset

static new_label(binary, name=None, function_name=None, original_addr=None, data_label=False)

class angr.analyses.reassembler.DataLabel(binary, original_addr, name=None)

Bases: Label

__init__(binary, original_addr, name=None)

property operand_str

g_label_ctr = count(0)

static new_label(binary, name=None, function_name=None, original_addr=None, data_label=False)

property offset

class angr.analyses.reassembler.FunctionLabel(binary, function_name, original_addr, plt=False)

Bases: Label

__init__(binary, function_name, original_addr, plt=False)

property function_name

property operand_str

g_label_ctr = count(0)

static new_label(binary, name=None, function_name=None, original_addr=None, data_label=False)

property offset

class angr.analyses.reassembler.ObjectLabel(binary, symbol_name, original_addr, plt=False)

Bases: Label

__init__(binary, symbol_name, original_addr, plt=False)

property symbol_name

property operand_str

g_label_ctr = count(0)

static new_label(binary, name=None, function_name=None, original_addr=None, data_label=False)

property offset

class angr.analyses.reassembler.NotypeLabel(binary, symbol_name, original_addr, plt=False)

Bases: Label

__init__(binary, symbol_name, original_addr, plt=False)

property symbol_name

property operand_str

g_label_ctr = count(0)

static new_label(binary, name=None, function_name=None, original_addr=None, data_label=False)

property offset

class angr.analyses.reassembler.SymbolManager(binary, cfg)

Bases: object

SymbolManager manages all symbols in the binary.

__init__(binary, cfg)

Constructor.

Parameters:

• binary (Reassembler) – The Binary analysis instance.

• cfg (angr.analyses.CFG) – The CFG analysis instance.

Returns:

None

get_unique_symbol_name(symbol_name)

new_label(addr, name=None, is_function=None, force=False)

label_got(addr, label)

Mark a certain label as assigned (to an instruction or a block of data).

Parameters:

• addr (int) – The address of the label.

• label (angr.analyses.reassembler.Label) – The label that is just assigned.

Returns:

None

class angr.analyses.reassembler.Operand(binary, insn_addr, insn_size, capstone_operand, operand_str, mnemonic, operand_offset, syntax=None)

Bases: object

__init__(binary, insn_addr, insn_size, capstone_operand, operand_str, mnemonic, operand_offset, syntax=None)

Constructor.

Parameters:

• binary (Reassembler) – The Binary analysis.

• insn_addr (int) – Address of the instruction.

• capstone_operand –

• operand_str (str) – the string representation of this operand

• mnemonic (str) – Mnemonic of the instruction that this operand belongs to.

• operand_offset (int) – offset of the operand into the instruction.

• syntax (str) – Provide a way to override the default syntax coming from binary.

Returns:

None

assembly()

property is_immediate

property symbolized

class angr.analyses.reassembler.Instruction(binary, addr, size, insn_bytes, capstone_instr)

Bases: object

High-level representation of an instruction in the binary

__init__(binary, addr, size, insn_bytes, capstone_instr)

Parameters:

• binary (Reassembler) – The Binary analysis

• addr (int) – Address of the instruction

• size (int) – Size of the instruction

• insn_bytes (str) – Instruction bytes

• capstone_instr – Capstone Instr object.

Returns:

None

assign_labels()

dbg_comments()

assembly(comments=False, symbolized=True)

Returns:

class angr.analyses.reassembler.BasicBlock(binary, addr, size, x86_getpc_retsite=False)

Bases: object

BasicBlock represents a basic block in the binary.

Parameters:

x86_getpc_retsite (bool) –

__init__(binary, addr, size, x86_getpc_retsite=False)

Constructor.

Parameters:

• binary (Reassembler) – The Binary analysis.

• addr (int) – Address of the block

• size (int) – Size of the block

• x86_getpc_retsite (bool) –

Returns:

None

assign_labels()

assembly(comments=False, symbolized=True)

instruction_addresses()

class angr.analyses.reassembler.Procedure(binary, function=None, addr=None, size=None, name=None, section='.text', asm_code=None)

Bases: object

Procedure in the binary.

__init__(binary, function=None, addr=None, size=None, name=None, section='.text', asm_code=None)

Constructor.

Parameters:

• binary (Reassembler) – The Binary analysis.

• function (angr.knowledge.Function) – The function it represents

• addr (int) – Address of the function. Not required if function is provided.

• size (int) – Size of the function. Not required if function is provided.

• section (str) – Which section this function comes from.

Returns:

None

property name

Get function name from the labels of the very first block. :return: Function name if there is any, None otherwise :rtype: string

property is_plt

If this function is a PLT entry or not. :return: True if this function is a PLT entry, False otherwise :rtype: bool

assign_labels()

assembly(comments=False, symbolized=True)

Get the assembly manifest of the procedure.

Parameters:

• comments –

• symbolized –

Returns:

A list of tuples (address, basic block assembly), ordered by basic block addresses

Return type:

list

instruction_addresses()

Get all instruction addresses in the binary.

Returns:

A list of sorted instruction addresses.

Return type:

list

class angr.analyses.reassembler.ProcedureChunk(project, addr, size)

Bases: Procedure

Procedure chunk.

__init__(project, addr, size)

Constructor.

Parameters:

• project –

• addr –

• size –

Returns:

assembly(comments=False, symbolized=True)

Get the assembly manifest of the procedure.

Parameters:

• comments –

• symbolized –

Returns:

A list of tuples (address, basic block assembly), ordered by basic block addresses

Return type:

list

assign_labels()

instruction_addresses()

Get all instruction addresses in the binary.

Returns:

A list of sorted instruction addresses.

Return type:

list

property is_plt

If this function is a PLT entry or not. :return: True if this function is a PLT entry, False otherwise :rtype: bool

property name

Get function name from the labels of the very first block. :return: Function name if there is any, None otherwise :rtype: string

class angr.analyses.reassembler.Data(binary, memory_data=None, section=None, section_name=None, name=None, size=None, sort=None, addr=None, initial_content=None)

Bases: object

__init__(binary, memory_data=None, section=None, section_name=None, name=None, size=None, sort=None, addr=None, initial_content=None)

property content

shrink(new_size)

Reduce the size of this block

Parameters:

new_size (int) – The new size

Returns:

None

desymbolize()

We believe this was a pointer and symbolized it before. Now we want to desymbolize it.

The following actions are performed: - Reload content from memory - Mark the sort as ‘unknown’

Returns:

None

assign_labels()

assembly(comments=False, symbolized=True)

class angr.analyses.reassembler.Relocation(addr, ref_addr, sort)

Bases: object

__init__(addr, ref_addr, sort)

class angr.analyses.reassembler.Reassembler(syntax='intel', remove_cgc_attachments=True, log_relocations=True)

Bases: Analysis

High-level representation of a binary with a linear representation of all instructions and data regions. After calling “symbolize”, it essentially acts as a binary reassembler.

Tested on CGC, x86 and x86-64 binaries.

Discliamer: The reassembler is an empirical solution. Don’t be surprised if it does not work on some binaries.

__init__(syntax='intel', remove_cgc_attachments=True, log_relocations=True)

property instructions

Get a list of all instructions in the binary

Returns:

A list of (address, instruction)

Return type:

tuple

property relocations

property inserted_asm_before_label

property inserted_asm_after_label

property main_executable_regions

return:

property main_nonexecutable_regions

return:

section_alignment(section_name)

Get the alignment for the specific section. If the section is not found, 16 is used as default.

Parameters:

section_name (str) – The section.

Returns:

The alignment in bytes.

Return type:

int

main_executable_regions_contain(addr)

Parameters:

addr –

Returns:

main_executable_region_limbos_contain(addr)

Sometimes there exists a pointer that points to a few bytes before the beginning of a section, or a few bytes after the beginning of the section. We take care of that here.

Parameters:

addr (int) – The address to check.

Returns:

A 2-tuple of (bool, the closest base address)

Return type:

tuple

main_nonexecutable_regions_contain(addr)

Parameters:

addr (int) – The address to check.

Returns:

True if the address is inside a non-executable region, False otherwise.

Return type:

bool

main_nonexecutable_region_limbos_contain(addr, tolerance_before=64, tolerance_after=64)

Sometimes there exists a pointer that points to a few bytes before the beginning of a section, or a few bytes after the beginning of the section. We take care of that here.

Parameters:

addr (int) – The address to check.

Returns:

A 2-tuple of (bool, the closest base address)

Return type:

tuple

register_instruction_reference(insn_addr, ref_addr, sort, operand_offset)

register_data_reference(data_addr, ref_addr)

add_label(name, addr)

Add a new label to the symbol manager.

Parameters:

• name (str) – Name of the label.

• addr (int) – Address of the label.

Returns:

None

insert_asm(addr, asm_code, before_label=False)

Insert some assembly code at the specific address. There must be an instruction starting at that address.

Parameters:

• addr (int) – Address of insertion

• asm_code (str) – The assembly code to insert

Returns:

None

append_procedure(name, asm_code)

Add a new procedure with specific name and assembly code.

Parameters:

• name (str) – The name of the new procedure.

• asm_code (str) – The assembly code of the procedure

Returns:

None

append_data(name, initial_content, size, readonly=False, sort='unknown')

Append a new data entry into the binary with specific name, content, and size.

Parameters:

• name (str) – Name of the data entry. Will be used as the label.

• initial_content (bytes) – The initial content of the data entry.

• size (int) – Size of the data entry.

• readonly (bool) – If the data entry belongs to the readonly region.

• sort (str) – Type of the data.

Returns:

None

remove_instruction(ins_addr)

Parameters:

ins_addr –

Returns:

randomize_procedures()

Returns:

symbolize()

assembly(comments=False, symbolized=True)

remove_cgc_attachments()

Remove CGC attachments.

Returns:

True if CGC attachments are found and removed, False otherwise

Return type:

bool

remove_unnecessary_stuff()

Remove unnecessary functions and data

Returns:

None

remove_unnecessary_stuff_glibc()

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

fast_memory_load(addr, size, data_type, endness='Iend_LE')

Load memory bytes from loader’s memory backend.

Parameters:

• addr (int) – The address to begin memory loading.

• size (int) – Size in bytes.

• data_type – Type of the data.

• endness (str) – Endianness of this memory load.

Returns:

Data read out of the memory.

Return type:

int or bytes or str or None

class angr.analyses.congruency_check.CongruencyCheck(throw=False)

Bases: Analysis

This is an analysis to ensure that angr executes things identically with different execution backends (i.e., unicorn vs vex).

__init__(throw=False)

Initializes a CongruencyCheck analysis.

Parameters:

throw – whether to raise an exception if an incongruency is found.

set_state_options(left_add_options=None, left_remove_options=None, right_add_options=None, right_remove_options=None)

Checks that the specified state options result in the same states over the next depth states.

set_states(left_state, right_state)

Checks that the specified paths stay the same over the next depth states.

set_simgr(simgr)

run(depth=None)

Checks that the paths in the specified path group stay the same over the next depth bytes.

The path group should have a “left” and a “right” stash, each with a single path.

compare_path_group(pg)

compare_states(sl, sr)

Compares two states for similarity.

compare_paths(pl, pr)

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

class angr.analyses.static_hooker.StaticHooker(library, binary=None)

Bases: Analysis

This analysis works on statically linked binaries - it finds the library functions statically linked into the binary and hooks them with the appropriate simprocedures.

Right now it only works on unstripped binaries, but hey! There’s room to grow!

__init__(library, binary=None)

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

class angr.analyses.binary_optimizer.ConstantPropagation(constant, constant_assignment_loc, constant_consuming_loc)

Bases: object

__init__(constant, constant_assignment_loc, constant_consuming_loc)

class angr.analyses.binary_optimizer.RedundantStackVariable(argument, stack_variable, stack_variable_consuming_locs)

Bases: object

__init__(argument, stack_variable, stack_variable_consuming_locs)

class angr.analyses.binary_optimizer.RegisterReallocation(stack_variable, register_variable, stack_variable_sources, stack_variable_consumers, prologue_addr, prologue_size, epilogue_addr, epilogue_size)

Bases: object

__init__(stack_variable, register_variable, stack_variable_sources, stack_variable_consumers, prologue_addr, prologue_size, epilogue_addr, epilogue_size)

Constructor.

Parameters:

• stack_variable (SimStackVariable) –

• register_variable (SimRegisterVariable) –

• stack_variable_sources (list) –

• stack_variable_consumers (list) –

• prologue_addr (int) –

• prologue_size (int) –

• epilogue_addr (int) –

• epilogue_size (int) –

class angr.analyses.binary_optimizer.DeadAssignment(pv)

Bases: object

__init__(pv)

Constructor.

Parameters:

pv (angr.analyses.ddg.ProgramVariable) – The assignment to remove.

class angr.analyses.binary_optimizer.BinaryOptimizer(cfg, techniques)

Bases: Analysis

This is a collection of binary optimization techniques we used in Mechanical Phish during the finals of Cyber Grand Challange. It focuses on dealing with some serious speed-impacting code constructs, and sort of worked on some CGC binaries compiled with O0. Use this analysis as a reference of how to use data dependency graph and such.

There is no guarantee that BinaryOptimizer will ever work on non-CGC binaries. Feel free to give us PR or MR, but please do not ask for support of non-CGC binaries.

BLOCKS_THRESHOLD = 500

__init__(cfg, techniques)

optimize()

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

class angr.analyses.callee_cleanup_finder.CalleeCleanupFinder(starts=None, hook_all=False)

Bases: Analysis

__init__(starts=None, hook_all=False)

analyze(addr)

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

class angr.analyses.dominance_frontier.DominanceFrontier(func, exception_edges=False)

Bases: Analysis

Computes the dominance frontier of all nodes in a function graph, and provides an easy-to-use interface for querying the frontier information.

__init__(func, exception_edges=False)

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

class angr.analyses.init_finder.SimEngineInitFinderVEX(project, replacements, overlay, pointers_only=False)

Bases: SimEngineLightVEXMixin, SimEngineLight

The VEX engine class for InitFinder.

__init__(project, replacements, overlay, pointers_only=False)

static is_concrete(expr)

Return type:

bool

static extract_offset_to_sp(spoffset_expr)

Extract the offset to the original stack pointer.

Parameters:

spoffset_expr (Base) – The claripy AST to parse.

Return type:

Optional[int]

Returns:

The offset to the original stack pointer, or None if spoffset_expr is not a supported type of SpOffset expression.

process(state, *args, **kwargs)

The main entry point for an engine. Should take a state and return a result.

Parameters:

state – The state to proceed from

Returns:

The result. Whatever you want ;)

static sp_offset(bits, offset)

Parameters:

• bits (int) –

• offset (int) –

class angr.analyses.init_finder.InitializationFinder(func=None, func_graph=None, block=None, max_iterations=1, replacements=None, overlay=None, pointers_only=False)

Bases: ForwardAnalysis, Analysis

Finds possible initializations for global data sections and generate an overlay to be used in other analyses later on.

__init__(func=None, func_graph=None, block=None, max_iterations=1, replacements=None, overlay=None, pointers_only=False)

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

abort()

Abort the analysis :return: None

downsize()

errors = []

property graph: DiGraph

has_job(job)

Checks whether there exists another job which has the same job key. :type job: TypeVar(JobType) :param job: The job to check.

Return type:

bool

Returns:

True if there exists another job with the same key, False otherwise.

Parameters:

job (JobType) –

property jobs

named_errors = {}

property should_abort

Should the analysis be terminated. :return: True/False

project: Project

kb: KnowledgeBase

class angr.analyses.xrefs.SimEngineXRefsVEX(xref_manager, project=None, replacements=None)

Bases: SimEngineLightVEXMixin, SimEngineLight

The VEX engine class for XRefs analysis.

__init__(xref_manager, project=None, replacements=None)

add_xref(xref_type, from_loc, to_loc)

static extract_value_if_concrete(expr)

Extract the concrete value from expr if it is a concrete claripy AST.

Parameters:

expr – A claripy AST.

Return type:

Optional[int]

Returns:

A concrete value or None if nothing concrete can be extracted.

static extract_offset_to_sp(spoffset_expr)

Extract the offset to the original stack pointer.

Parameters:

spoffset_expr (Base) – The claripy AST to parse.

Return type:

Optional[int]

Returns:

The offset to the original stack pointer, or None if spoffset_expr is not a supported type of SpOffset expression.

process(state, *args, **kwargs)

The main entry point for an engine. Should take a state and return a result.

Parameters:

state – The state to proceed from

Returns:

The result. Whatever you want ;)

static sp_offset(bits, offset)

Parameters:

• bits (int) –

• offset (int) –

class angr.analyses.xrefs.XRefsAnalysis(func=None, func_graph=None, block=None, max_iterations=1, replacements=None)

Bases: ForwardAnalysis, Analysis

XRefsAnalysis recovers in-depth x-refs (cross-references) in disassembly code.

Here is an example:

.text:
000023C8                 LDR     R2, =time_now
000023CA                 LDR     R3, [R2]
000023CC                 ADDS    R3, #1
000023CE                 STR     R3, [R2]
000023D0                 BX      LR

.bss:
1FFF36F4 time_now        % 4

You will have the following x-refs for time_now:

23c8 - offset
23ca - read access
23ce - write access

__init__(func=None, func_graph=None, block=None, max_iterations=1, replacements=None)

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

abort()

Abort the analysis :return: None

downsize()

errors = []

property graph: DiGraph

has_job(job)

Checks whether there exists another job which has the same job key. :type job: TypeVar(JobType) :param job: The job to check.

Return type:

bool

Returns:

True if there exists another job with the same key, False otherwise.

Parameters:

job (JobType) –

property jobs

named_errors = {}

property should_abort

Should the analysis be terminated. :return: True/False

project: Project

kb: KnowledgeBase

class angr.analyses.proximity_graph.ProxiNodeTypes

Bases: object

Node Type Enums

Empty = 0

String = 1

Function = 2

FunctionCall = 3

Integer = 4

Unknown = 5

Variable = 6

class angr.analyses.proximity_graph.BaseProxiNode(type_, ref_at=None)

Bases: object

Base class for all nodes in a proximity graph.

Parameters:

• type_ (int) –

• ref_at (Set[int] | None) –

__init__(type_, ref_at=None)

Parameters:

• type_ (int) –

• ref_at (Set[int] | None) –

class angr.analyses.proximity_graph.FunctionProxiNode(func, ref_at=None)

Bases: BaseProxiNode

Proximity node showing current and expanded function calls in graph.

Parameters:

ref_at (Set[int] | None) –

__init__(func, ref_at=None)

Parameters:

ref_at (Set[int] | None) –

class angr.analyses.proximity_graph.VariableProxiNode(addr, name, ref_at=None)

Bases: BaseProxiNode

Variable arg node

Parameters:

ref_at (Set[int] | None) –

__init__(addr, name, ref_at=None)

Parameters:

ref_at (Set[int] | None) –

class angr.analyses.proximity_graph.StringProxiNode(addr, content, ref_at=None)

Bases: BaseProxiNode

String arg node

Parameters:

ref_at (Set[int] | None) –

__init__(addr, content, ref_at=None)

Parameters:

ref_at (Set[int] | None) –

class angr.analyses.proximity_graph.CallProxiNode(callee, ref_at=None, args=None)

Bases: BaseProxiNode

Call node

Parameters:

• ref_at (Set[int] | None) –

• args (Tuple[BaseProxiNode] | None) –

__init__(callee, ref_at=None, args=None)

Parameters:

• ref_at (Set[int] | None) –

• args (Tuple[BaseProxiNode] | None) –

class angr.analyses.proximity_graph.IntegerProxiNode(value, ref_at=None)

Bases: BaseProxiNode

Int arg node

Parameters:

• value (int) –

• ref_at (Set[int] | None) –

__init__(value, ref_at=None)

Parameters:

• value (int) –

• ref_at (Set[int] | None) –

class angr.analyses.proximity_graph.UnknownProxiNode(dummy_value)

Bases: BaseProxiNode

Unknown arg node

Parameters:

dummy_value (str) –

__init__(dummy_value)

Parameters:

dummy_value (str) –

class angr.analyses.proximity_graph.ProximityGraphAnalysis(func, cfg_model, xrefs, decompilation=None, expand_funcs=None)

Bases: Analysis

Generate a proximity graph.

Parameters:

• func (Function) –

• cfg_model (CFGModel) –

• xrefs (XRefManager) –

• decompilation (Decompiler | None) –

• expand_funcs (Set[int] | None) –

__init__(func, cfg_model, xrefs, decompilation=None, expand_funcs=None)

Parameters:

• func (Function) –

• cfg_model (CFGModel) –

• xrefs (XRefManager) –

• decompilation (Decompiler | None) –

• expand_funcs (Set[int] | None) –

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

Defines analysis that will generate a dynamic data-dependency graph

class angr.analyses.data_dep.data_dependency_analysis.NodalAnnotation(node)

Bases: Annotation

Allows a node to be stored as an annotation to a BV in a DefaultMemory instance

Parameters:

node (BaseDepNode) –

__init__(node)

Parameters:

node (BaseDepNode) –

property relocatable: bool

Can not be relocated in a simplification

property eliminatable

Can not be eliminated in a simplification

relocate(src, dst)

This is called when an annotation has to be relocated because of simplifications.

Consider the following case:

x = claripy.BVS(‘x’, 32) zero = claripy.BVV(0, 32).add_annotation(your_annotation) y = x + zero

Here, one of three things can happen:

1. if your_annotation.eliminatable is True, the simplifiers will simply eliminate your_annotation along with zero and y is x will hold

2. elif your_annotation.relocatable is False, the simplifier will abort and y will never be simplified

3. elif your_annotation.relocatable is True, the simplifier will run, determine that the simplified result of x + zero will be x. It will then call your_annotation.relocate(zero, x) to move the annotation away from the AST that is about to be eliminated.

Parameters:

• src – the old AST that was eliminated in the simplification

• dst – the new AST (the result of a simplification)

Returns:

the annotation that will be applied to dst

class angr.analyses.data_dep.data_dependency_analysis.DataDependencyGraphAnalysis(end_state, start_from=None, end_at=None, block_addrs=None)

Bases: Analysis

This is a DYNAMIC data dependency graph that utilizes a given SimState to produce a DDG graph that is accurate to the path the program took during execution.

This analysis utilizes the SimActionData objects present in the provided SimState’s action history to generate the dependency graph.

Parameters:

• end_state (SimState) –

• start_from (int | None) –

• end_at (int | None) –

• block_addrs (List[int] | None) –

__init__(end_state, start_from=None, end_at=None, block_addrs=None)

Parameters:

• end_state (SimState) – Simulation state used to extract all SimActionData

• start_from (Optional[int]) – An address or None, Specifies where to start generation of DDG

• end_at (Optional[int]) – An address or None, Specifies where to end generation of DDG

• block_addrs (List[int] | None) – List of block addresses that the DDG analysis should be run on

• block_addrs –

property graph: DiGraph | None

property simplified_graph: DiGraph | None

property sub_graph: DiGraph | None

get_data_dep(g_node, include_tmp_nodes, backwards)

Return type:

Optional[DiGraph]

Parameters:

• g_node (BaseDepNode) –

• include_tmp_nodes (bool) –

• backwards (bool) –

errors = []

named_errors = {}

project: Project

kb: KnowledgeBase

class angr.analyses.data_dep.sim_act_location.SimActLocation(bbl_addr, ins_addr, stmt_idx)

Bases: object

Structure-like class used to bundle the instruction address and statement index of a given SimAction in order to uniquely identify a given SimAction

Parameters:

• bbl_addr (int) –

• ins_addr (int) –

• stmt_idx (int) –

__init__(bbl_addr, ins_addr, stmt_idx)

Parameters:

• bbl_addr (int) –

• ins_addr (int) –

• stmt_idx (int) –

class angr.analyses.data_dep.sim_act_location.ParsedInstruction(ins_addr, min_stmt_idx, max_stmt_idx)

Bases: object

Used by parser to facilitate linking with recent ancestors in an efficient manner

Parameters:

• ins_addr (int) –

• min_stmt_idx (int) –

• max_stmt_idx (int) –

__init__(ins_addr, min_stmt_idx, max_stmt_idx)

Parameters:

• ins_addr (int) –

• min_stmt_idx (int) –

• max_stmt_idx (int) –

class angr.analyses.data_dep.dep_nodes.DepNodeTypes

Bases: object

Enumeration of types of BaseDepNode supported by this analysis

Memory = 1

Register = 2

Tmp = 3

Constant = 4

class angr.analyses.data_dep.dep_nodes.BaseDepNode(type_, sim_act)

Bases: object

Base class for all nodes in a data-dependency graph

Parameters:

• type_ (int) –

• sim_act (SimActionData) –

__init__(type_, sim_act)

Parameters:

• type_ (int) –

• sim_act (SimActionData) –

value_tuple()

Return type:

Tuple[BV, int]

Returns:

A tuple containing the node’s value as a BV and as an evaluated integer

property ast: BV

property type: int

Getter :return: An integer defined in DepNodeTypes, represents the subclass type of this DepNode.

class angr.analyses.data_dep.dep_nodes.ConstantDepNode(sim_act, value)

Bases: BaseDepNode

Used to create a DepNode that will hold a constant, numeric value Uniquely identified by its value

Parameters:

• sim_act (SimActionData) –

• value (int) –

__init__(sim_act, value)

Parameters:

• sim_act (SimActionData) –

• value (int) –

property ast: BV

property type: int

Getter :return: An integer defined in DepNodeTypes, represents the subclass type of this DepNode.

value_tuple()

Return type:

Tuple[BV, int]

Returns:

A tuple containing the node’s value as a BV and as an evaluated integer

class angr.analyses.data_dep.dep_nodes.MemDepNode(sim_act, addr)

Bases: BaseDepNode

Used to represent SimActions of type MEM

Parameters:

• sim_act (SimActionData) –

• addr (int) –

__init__(sim_act, addr)

Parameters:

• sim_act (SimActionData) –

• addr (int) –

property width: int

classmethod cast_to_mem(base_dep_node)

Casts a BaseDepNode into a MemDepNode

Parameters:

base_dep_node (BaseDepNode) –

property ast: BV

property type: int

Getter :return: An integer defined in DepNodeTypes, represents the subclass type of this DepNode.

value_tuple()

Return type:

Tuple[BV, int]

Returns:

A tuple containing the node’s value as a BV and as an evaluated integer

class angr.analyses.data_dep.dep_nodes.VarDepNode(type_, sim_act, reg, arch_name='')

Bases: BaseDepNode

Abstract class for representing SimActions of TYPE reg or tmp

Parameters:

• type_ (int) –

• sim_act (SimActionData) –

• reg (int) –

• arch_name (str) –

__init__(type_, sim_act, reg, arch_name='')

Parameters:

• type_ (int) –

• sim_act (SimActionData) –

• reg (int) –

• arch_name (str) –

property display_name: str

property ast: BV

property type: int

Getter :return: An integer defined in DepNodeTypes, represents the subclass type of this DepNode.

value_tuple()

Return type:

Tuple[BV, int]

Returns:

A tuple containing the node’s value as a BV and as an evaluated integer

class angr.analyses.data_dep.dep_nodes.TmpDepNode(sim_act, reg, arch_name='')

Bases: VarDepNode

Used to represent SimActions of type TMP

Parameters:

• sim_act (SimActionData) –

• reg (int) –

• arch_name (str) –

__init__(sim_act, reg, arch_name='')

Parameters:

• sim_act (SimActionData) –

• reg (int) –

• arch_name (str) –

property ast: BV

property display_name: str

property type: int

Getter :return: An integer defined in DepNodeTypes, represents the subclass type of this DepNode.

value_tuple()

Return type:

Tuple[BV, int]

Returns:

A tuple containing the node’s value as a BV and as an evaluated integer

class angr.analyses.data_dep.dep_nodes.RegDepNode(sim_act, reg, arch_name='')

Bases: VarDepNode

Base class for representing SimActions of TYPE reg

Parameters:

• sim_act (SimActionData) –

• reg (int) –

• arch_name (str) –

__init__(sim_act, reg, arch_name='')

Parameters:

• sim_act (SimActionData) –

• reg (int) –

• arch_name (str) –

property ast: BV

property display_name: str

property reg_size: int

property type: int

Getter :return: An integer defined in DepNodeTypes, represents the subclass type of this DepNode.

value_tuple()

Return type:

Tuple[BV, int]

Returns:

A tuple containing the node’s value as a BV and as an evaluated integer

class angr.blade.Blade(graph, dst_run, dst_stmt_idx, direction='backward', project=None, cfg=None, ignore_sp=False, ignore_bp=False, ignored_regs=None, max_level=3, base_state=None, stop_at_calls=False, cross_insn_opt=False, max_predecessors=10, include_imarks=True)

Bases: object

Blade is a light-weight program slicer that works with networkx DiGraph containing CFGNodes. It is meant to be used in angr for small or on-the-fly analyses.

Parameters:

• graph (DiGraph) –

• dst_run (int) –

• dst_stmt_idx (int) –

• direction (str) –

• ignore_sp (bool) –

• ignore_bp (bool) –

• max_level (int) –

• stop_at_calls (bool) –

• max_predecessors (int) –

• include_imarks (bool) –

__init__(graph, dst_run, dst_stmt_idx, direction='backward', project=None, cfg=None, ignore_sp=False, ignore_bp=False, ignored_regs=None, max_level=3, base_state=None, stop_at_calls=False, cross_insn_opt=False, max_predecessors=10, include_imarks=True)

Parameters:

• graph (DiGraph) – A graph representing the control flow graph. Note that it does not take angr.analyses.CFGEmulated or angr.analyses.CFGFast.

• dst_run (int) – An address specifying the target SimRun.

• dst_stmt_idx (int) – The target statement index. -1 means executing until the last statement.

• direction (str) – ‘backward’ or ‘forward’ slicing. Forward slicing is not yet supported.

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

• cfg (angr.analyses.CFGBase) – the CFG instance. It will be made mandatory later.

• ignore_sp (bool) – Whether the stack pointer should be ignored in dependency tracking. Any dependency from/to stack pointers will be ignored if this options is True.

• ignore_bp (bool) – Whether the base pointer should be ignored or not.

• max_level (int) – The maximum number of blocks that we trace back for.

• stop_at_calls (bool) – Limit slicing within a single function. Do not proceed when encounters a call edge.

• include_imarks (bool) – Should IMarks (instruction boundaries) be included in the slice.

• max_predecessors (int) –

Returns:

None

property slice

dbg_repr(arch=None)

class angr.slicer.SimLightState(temps=None, regs=None, stack_offsets=None, options=None)

Bases: object

Represents a program state. Only used in SimSlicer.

__init__(temps=None, regs=None, stack_offsets=None, options=None)

temps

regs

stack_offsets

options

class angr.slicer.SimSlicer(arch, statements, target_tmps=None, target_regs=None, target_stack_offsets=None, inslice_callback=None, inslice_callback_infodict=None, include_imarks=True)

Bases: object

A super lightweight intra-IRSB slicing class.

Parameters:

include_imarks (bool) –

__init__(arch, statements, target_tmps=None, target_regs=None, target_stack_offsets=None, inslice_callback=None, inslice_callback_infodict=None, include_imarks=True)

Parameters:

include_imarks (bool) –

class angr.annocfg.AnnotatedCFG(project, cfg=None, detect_loops=False)

Bases: object

AnnotatedCFG is a control flow graph with statement whitelists and exit whitelists to describe a slice of the program.

__init__(project, cfg=None, detect_loops=False)

Constructor.

Parameters:

• project – The angr Project instance

• cfg – Control flow graph.

• detect_loops –

from_digraph(digraph)

Initialize this AnnotatedCFG object with a networkx.DiGraph consisting of the following form of nodes:

Tuples like (block address, statement ID)

Those nodes are connected by edges indicating the execution flow.

Parameters:

digraph (networkx.DiGraph) – A networkx.DiGraph object

get_addr(run)

add_block_to_whitelist(block)

add_statements_to_whitelist(block, stmt_ids)

add_exit_to_whitelist(run_from, run_to)

set_last_statement(block_addr, stmt_id)

add_loop(loop_tuple)

A loop tuple contains a series of IRSB addresses that form a loop. Ideally it always starts with the first IRSB that we meet during the execution.

should_take_exit(addr_from, addr_to)

should_execute_statement(addr, stmt_id)

get_run(addr)

get_whitelisted_statements(addr)

Returns:

True if all statements are whitelisted

get_last_statement_index(addr)

Get the statement index of the last statement to execute in the basic block specified by addr.

Parameters:

addr (int) – Address of the basic block.

Returns:

The statement index of the last statement to be executed in the block. Usually if the default exit is taken, it will be the last statement to execute. If the block is not in the slice or we should never take any exit going to this block, None is returned.

Return type:

int or None

get_loops()

get_targets(source_addr)

dbg_repr()

dbg_print_irsb(irsb_addr, project=None)

Pretty-print an IRSB with whitelist information

keep_path(path)

Given a path, returns True if the path should be kept, False if it should be cut.

merge_points(path)

successor_func(path)

Callback routine that takes in a path, and returns all feasible successors to path group. This callback routine should be passed to the keyword argument “successor_func” of PathGroup.step().

Parameters:

path – A Path instance.

Returns:

A list of all feasible Path successors.

angr.codenode.repr_addr(addr)

class angr.codenode.CodeNode(addr, size, graph=None, thumb=False)

Bases: object

__init__(addr, size, graph=None, thumb=False)

addr

size

thumb

successors()

Return type:

List[CodeNode]

predecessors()

is_hook = None

class angr.codenode.BlockNode(addr, size, bytestr=None, **kwargs)

Bases: CodeNode

is_hook = False

__init__(addr, size, bytestr=None, **kwargs)

bytestr

addr

predecessors()

size

successors()

Return type:

List[CodeNode]

thumb

class angr.codenode.SootBlockNode(addr, size, stmts, **kwargs)

Bases: BlockNode

__init__(addr, size, stmts, **kwargs)

stmts

addr

bytestr

is_hook = False

predecessors()

size

successors()

Return type:

List[CodeNode]

thumb

class angr.codenode.HookNode(addr, size, sim_procedure, **kwargs)

Bases: CodeNode

is_hook = True

__init__(addr, size, sim_procedure, **kwargs)

Parameters:

sim_procedure (type) – the the sim_procedure class

sim_procedure

addr

predecessors()

size

successors()

Return type:

List[CodeNode]

thumb

class angr.codenode.SyscallNode(addr, size, sim_procedure, **kwargs)

Bases: HookNode

is_hook = False

sim_procedure

__init__(addr, size, sim_procedure, **kwargs)

Parameters:

sim_procedure (type) – the the sim_procedure class

addr

predecessors()

size

successors()

Return type:

List[CodeNode]

thumb

SimOS

Manage OS-level configuration.

angr.simos.register_simos(name, cls)

class angr.simos.simos.SimOS(project, name=None)

Bases: object

A class describing OS/arch-level configuration.

Parameters:

project (angr.Project) –

__init__(project, name=None)

Parameters:

project (Project) –

configure_project()

Configure the project to set up global settings (like SimProcedures).

state_blank(addr=None, initial_prefix=None, brk=None, stack_end=None, stack_size=8388608, stdin=None, thread_idx=None, permissions_backer=None, **kwargs)

Initialize a blank state.

All parameters are optional.

Parameters:

• addr – The execution start address.

• initial_prefix –

• stack_end – The end of the stack (i.e., the byte after the last valid stack address).

• stack_size – The number of bytes to allocate for stack space

• brk – The address of the process’ break.

Returns:

The initialized SimState.

Any additional arguments will be passed to the SimState constructor

state_entry(**kwargs)

state_full_init(**kwargs)

state_call(addr, *args, **kwargs)

prepare_call_state(calling_state, initial_state=None, preserve_registers=(), preserve_memory=())

This function prepares a state that is executing a call instruction. If given an initial_state, it copies over all of the critical registers to it from the calling_state. Otherwise, it prepares the calling_state for action.

This is mostly used to create minimalistic for CFG generation. Some ABIs, such as MIPS PIE and x86 PIE, require certain information to be maintained in certain registers. For example, for PIE MIPS, this function transfer t9, gp, and ra to the new state.

prepare_function_symbol(symbol_name, basic_addr=None)

Prepare the address space with the data necessary to perform relocations pointing to the given symbol

Returns a 2-tuple. The first item is the address of the function code, the second is the address of the relocation target.

handle_exception(successors, engine, exception)

Perform exception handling. This method will be called when, during execution, a SimException is thrown. Currently, this can only indicate a segfault, but in the future it could indicate any unexpected exceptional behavior that can’t be handled by ordinary control flow.

The method may mutate the provided SimSuccessors object in any way it likes, or re-raise the exception.

Parameters:

• successors – The SimSuccessors object currently being executed on

• engine – The engine that was processing this step

• exception – The actual exception object

syscall(state, allow_unsupported=True)

syscall_abi(state)

Return type:

str

syscall_cc(state)

Return type:

Optional[SimCCSyscall]

is_syscall_addr(addr)

syscall_from_addr(addr, allow_unsupported=True)

syscall_from_number(number, allow_unsupported=True, abi=None)

setup_gdt(state, gdt)

Write the GlobalDescriptorTable object in the current state memory

Parameters:

• state – state in which to write the GDT

• gdt – GlobalDescriptorTable object

Returns:

generate_gdt(fs, gs, fs_size=4294967295, gs_size=4294967295)

Generate a GlobalDescriptorTable object and populate it using the value of the gs and fs register

Parameters:

• fs – value of the fs segment register

• gs – value of the gs segment register

• fs_size – size of the fs segment register

• gs_size – size of the gs segment register

Returns:

gdt a GlobalDescriptorTable object

class angr.simos.simos.GlobalDescriptorTable(addr, limit, table, gdt_sel, cs_sel, ds_sel, es_sel, ss_sel, fs_sel, gs_sel)

Bases: object

__init__(addr, limit, table, gdt_sel, cs_sel, ds_sel, es_sel, ss_sel, fs_sel, gs_sel)

class angr.simos.linux.SimLinux(project, **kwargs)

Bases: SimUserland

OS-specific configuration for *nix-y OSes.

__init__(project, **kwargs)

configure_project()

Configure the project to set up global settings (like SimProcedures).

syscall_abi(state)

Optionally, override this function to determine which abi is being used for the state’s current syscall.

state_blank(fs=None, concrete_fs=False, chroot=None, cwd=None, pathsep=b'/', thread_idx=None, init_libc=False, **kwargs)

Initialize a blank state.

All parameters are optional.

Parameters:

• addr – The execution start address.

• initial_prefix –

• stack_end – The end of the stack (i.e., the byte after the last valid stack address).

• stack_size – The number of bytes to allocate for stack space

• brk – The address of the process’ break.

Returns:

The initialized SimState.

Any additional arguments will be passed to the SimState constructor

state_entry(args=None, env=None, argc=None, **kwargs)

set_entry_register_values(state)

state_full_init(**kwargs)

prepare_function_symbol(symbol_name, basic_addr=None)

Prepare the address space with the data necessary to perform relocations pointing to the given symbol.

Returns a 2-tuple. The first item is the address of the function code, the second is the address of the relocation target.

initialize_segment_register_x64(state, concrete_target)

Set the fs register in the angr to the value of the fs register in the concrete process

Parameters:

• state – state which will be modified

• concrete_target – concrete target that will be used to read the fs register

Returns:

None

initialize_gdt_x86(state, concrete_target)

Create a GDT in the state memory and populate the segment registers. Rehook the vsyscall address using the real value in the concrete process memory

Parameters:

• state – state which will be modified

• concrete_target – concrete target that will be used to read the fs register

Returns:

get_segment_register_name()

generate_gdt(fs, gs, fs_size=4294967295, gs_size=4294967295)

Generate a GlobalDescriptorTable object and populate it using the value of the gs and fs register

Parameters:

• fs – value of the fs segment register

• gs – value of the gs segment register

• fs_size – size of the fs segment register

• gs_size – size of the gs segment register

Returns:

gdt a GlobalDescriptorTable object

handle_exception(successors, engine, exception)

Perform exception handling. This method will be called when, during execution, a SimException is thrown. Currently, this can only indicate a segfault, but in the future it could indicate any unexpected exceptional behavior that can’t be handled by ordinary control flow.

The method may mutate the provided SimSuccessors object in any way it likes, or re-raise the exception.

Parameters:

• successors – The SimSuccessors object currently being executed on

• engine – The engine that was processing this step

• exception – The actual exception object

is_syscall_addr(addr)

Return whether or not the given address corresponds to a syscall implementation.

prepare_call_state(calling_state, initial_state=None, preserve_registers=(), preserve_memory=())

This function prepares a state that is executing a call instruction. If given an initial_state, it copies over all of the critical registers to it from the calling_state. Otherwise, it prepares the calling_state for action.

This is mostly used to create minimalistic for CFG generation. Some ABIs, such as MIPS PIE and x86 PIE, require certain information to be maintained in certain registers. For example, for PIE MIPS, this function transfer t9, gp, and ra to the new state.

setup_gdt(state, gdt)

Write the GlobalDescriptorTable object in the current state memory

Parameters:

• state – state in which to write the GDT

• gdt – GlobalDescriptorTable object

Returns:

state_call(addr, *args, **kwargs)

syscall(state, allow_unsupported=True)

Given a state, return the procedure corresponding to the current syscall. This procedure will have .syscall_number, .display_name, and .addr set.

Parameters:

• state – The state to get the syscall number from

• allow_unsupported – Whether to return a “dummy” sycall instead of raising an unsupported exception

syscall_cc(state)

Return type:

SimCCSyscall

syscall_from_addr(addr, allow_unsupported=True)

Get a syscall SimProcedure from an address.

Parameters:

• addr – The address to convert to a syscall SimProcedure

• allow_unsupported – Whether to return a dummy procedure for an unsupported syscall instead of raising an exception.

Returns:

The SimProcedure for the syscall, or None if the address is not a syscall address.

syscall_from_number(number, allow_unsupported=True, abi=None)

Get a syscall SimProcedure from its number.

Parameters:

• number – The syscall number

• allow_unsupported – Whether to return a “stub” syscall for unsupported numbers instead of throwing an error

• abi – The name of the abi to use. If None, will assume that the abis have disjoint numbering schemes and pick the right one.

Returns:

The SimProcedure for the syscall

class angr.simos.cgc.SimCGC(project, **kwargs)

Bases: SimUserland

Environment configuration for the CGC DECREE platform

__init__(project, **kwargs)

state_blank(flag_page=None, allocate_stack_page_count=256, **kwargs)

Parameters:

• flag_page – Flag page content, either a string or a list of BV8s

• allocate_stack_page_count – Number of pages to pre-allocate for stack

state_entry(add_options=None, **kwargs)

configure_project(abi_list=None)

Configure the project to set up global settings (like SimProcedures).

generate_gdt(fs, gs, fs_size=4294967295, gs_size=4294967295)

Generate a GlobalDescriptorTable object and populate it using the value of the gs and fs register

Parameters:

• fs – value of the fs segment register

• gs – value of the gs segment register

• fs_size – size of the fs segment register

• gs_size – size of the gs segment register

Returns:

gdt a GlobalDescriptorTable object

handle_exception(successors, engine, exception)

Perform exception handling. This method will be called when, during execution, a SimException is thrown. Currently, this can only indicate a segfault, but in the future it could indicate any unexpected exceptional behavior that can’t be handled by ordinary control flow.

The method may mutate the provided SimSuccessors object in any way it likes, or re-raise the exception.

Parameters:

• successors – The SimSuccessors object currently being executed on

• engine – The engine that was processing this step

• exception – The actual exception object

is_syscall_addr(addr)

Return whether or not the given address corresponds to a syscall implementation.

prepare_call_state(calling_state, initial_state=None, preserve_registers=(), preserve_memory=())

This function prepares a state that is executing a call instruction. If given an initial_state, it copies over all of the critical registers to it from the calling_state. Otherwise, it prepares the calling_state for action.

This is mostly used to create minimalistic for CFG generation. Some ABIs, such as MIPS PIE and x86 PIE, require certain information to be maintained in certain registers. For example, for PIE MIPS, this function transfer t9, gp, and ra to the new state.

prepare_function_symbol(symbol_name, basic_addr=None)

Prepare the address space with the data necessary to perform relocations pointing to the given symbol

Returns a 2-tuple. The first item is the address of the function code, the second is the address of the relocation target.

setup_gdt(state, gdt)

Write the GlobalDescriptorTable object in the current state memory

Parameters:

• state – state in which to write the GDT

• gdt – GlobalDescriptorTable object

Returns:

state_call(addr, *args, **kwargs)

state_full_init(**kwargs)

syscall(state, allow_unsupported=True)

Given a state, return the procedure corresponding to the current syscall. This procedure will have .syscall_number, .display_name, and .addr set.

Parameters:

• state – The state to get the syscall number from

• allow_unsupported – Whether to return a “dummy” sycall instead of raising an unsupported exception

syscall_abi(state)

Optionally, override this function to determine which abi is being used for the state’s current syscall.

syscall_cc(state)

Return type:

SimCCSyscall

syscall_from_addr(addr, allow_unsupported=True)

Get a syscall SimProcedure from an address.

Parameters:

• addr – The address to convert to a syscall SimProcedure

• allow_unsupported – Whether to return a dummy procedure for an unsupported syscall instead of raising an exception.

Returns:

The SimProcedure for the syscall, or None if the address is not a syscall address.

syscall_from_number(number, allow_unsupported=True, abi=None)

Get a syscall SimProcedure from its number.

Parameters:

• number – The syscall number

• allow_unsupported – Whether to return a “stub” syscall for unsupported numbers instead of throwing an error

• abi – The name of the abi to use. If None, will assume that the abis have disjoint numbering schemes and pick the right one.

Returns:

The SimProcedure for the syscall

class angr.simos.userland.SimUserland(project, syscall_library=None, syscall_addr_alignment=4, **kwargs)

Bases: SimOS

This is a base class for any SimOS that wants to support syscalls.

It uses the CLE kernel object to provide addresses for syscalls. Syscalls will be emulated as a jump to one of these addresses, where a SimProcedure from the syscall library provided at construction time will be executed.

__init__(project, syscall_library=None, syscall_addr_alignment=4, **kwargs)

configure_project(abi_list=None)

Configure the project to set up global settings (like SimProcedures).

syscall_cc(state)

Return type:

SimCCSyscall

syscall(state, allow_unsupported=True)

Given a state, return the procedure corresponding to the current syscall. This procedure will have .syscall_number, .display_name, and .addr set.

Parameters:

• state – The state to get the syscall number from

• allow_unsupported – Whether to return a “dummy” sycall instead of raising an unsupported exception

syscall_abi(state)

Optionally, override this function to determine which abi is being used for the state’s current syscall.

is_syscall_addr(addr)

Return whether or not the given address corresponds to a syscall implementation.

syscall_from_addr(addr, allow_unsupported=True)

Get a syscall SimProcedure from an address.

Parameters:

• addr – The address to convert to a syscall SimProcedure

• allow_unsupported – Whether to return a dummy procedure for an unsupported syscall instead of raising an exception.

Returns:

The SimProcedure for the syscall, or None if the address is not a syscall address.

syscall_from_number(number, allow_unsupported=True, abi=None)

Get a syscall SimProcedure from its number.

Parameters:

• number – The syscall number

• allow_unsupported – Whether to return a “stub” syscall for unsupported numbers instead of throwing an error

• abi – The name of the abi to use. If None, will assume that the abis have disjoint numbering schemes and pick the right one.

Returns:

The SimProcedure for the syscall

generate_gdt(fs, gs, fs_size=4294967295, gs_size=4294967295)

Generate a GlobalDescriptorTable object and populate it using the value of the gs and fs register

Parameters:

• fs – value of the fs segment register

• gs – value of the gs segment register

• fs_size – size of the fs segment register

• gs_size – size of the gs segment register

Returns:

gdt a GlobalDescriptorTable object

handle_exception(successors, engine, exception)

Perform exception handling. This method will be called when, during execution, a SimException is thrown. Currently, this can only indicate a segfault, but in the future it could indicate any unexpected exceptional behavior that can’t be handled by ordinary control flow.

The method may mutate the provided SimSuccessors object in any way it likes, or re-raise the exception.

Parameters:

• successors – The SimSuccessors object currently being executed on

• engine – The engine that was processing this step

• exception – The actual exception object

prepare_call_state(calling_state, initial_state=None, preserve_registers=(), preserve_memory=())

This function prepares a state that is executing a call instruction. If given an initial_state, it copies over all of the critical registers to it from the calling_state. Otherwise, it prepares the calling_state for action.

This is mostly used to create minimalistic for CFG generation. Some ABIs, such as MIPS PIE and x86 PIE, require certain information to be maintained in certain registers. For example, for PIE MIPS, this function transfer t9, gp, and ra to the new state.

prepare_function_symbol(symbol_name, basic_addr=None)

Prepare the address space with the data necessary to perform relocations pointing to the given symbol

Returns a 2-tuple. The first item is the address of the function code, the second is the address of the relocation target.

setup_gdt(state, gdt)

Write the GlobalDescriptorTable object in the current state memory

Parameters:

• state – state in which to write the GDT

• gdt – GlobalDescriptorTable object

Returns:

state_blank(addr=None, initial_prefix=None, brk=None, stack_end=None, stack_size=8388608, stdin=None, thread_idx=None, permissions_backer=None, **kwargs)

Initialize a blank state.

All parameters are optional.

Parameters:

• addr – The execution start address.

• initial_prefix –

• stack_end – The end of the stack (i.e., the byte after the last valid stack address).

• stack_size – The number of bytes to allocate for stack space

• brk – The address of the process’ break.

Returns:

The initialized SimState.

Any additional arguments will be passed to the SimState constructor

state_call(addr, *args, **kwargs)

state_entry(**kwargs)

state_full_init(**kwargs)

class angr.simos.windows.SecurityCookieInit(value)

Bases: Enum

An enumeration.

NONE = 0

RANDOM = 1

STATIC = 2

SYMBOLIC = 3

class angr.simos.windows.SimWindows(project)

Bases: SimOS

Environment for the Windows Win32 subsystem. Does not support syscalls currently.

__init__(project)

configure_project()

Configure the project to set up global settings (like SimProcedures).

state_entry(args=None, env=None, argc=None, **kwargs)

state_blank(thread_idx=None, **kwargs)

Initialize a blank state.

All parameters are optional.

Parameters:

• addr – The execution start address.

• initial_prefix –

• stack_end – The end of the stack (i.e., the byte after the last valid stack address).

• stack_size – The number of bytes to allocate for stack space

• brk – The address of the process’ break.

Returns:

The initialized SimState.

Any additional arguments will be passed to the SimState constructor

handle_exception(successors, engine, exception)

Perform exception handling. This method will be called when, during execution, a SimException is thrown. Currently, this can only indicate a segfault, but in the future it could indicate any unexpected exceptional behavior that can’t be handled by ordinary control flow.

The method may mutate the provided SimSuccessors object in any way it likes, or re-raise the exception.

Parameters:

• successors – The SimSuccessors object currently being executed on

• engine – The engine that was processing this step

• exception – The actual exception object

initialize_segment_register_x64(state, concrete_target)

Set the gs register in the angr to the value of the fs register in the concrete process

Parameters:

• state – state which will be modified

• concrete_target – concrete target that will be used to read the fs register

Returns:

None

initialize_gdt_x86(state, concrete_target)

Create a GDT in the state memory and populate the segment registers.

Parameters:

• state – state which will be modified

• concrete_target – concrete target that will be used to read the fs register

Returns:

the created GlobalDescriptorTable object

get_segment_register_name()

generate_gdt(fs, gs, fs_size=4294967295, gs_size=4294967295)

Generate a GlobalDescriptorTable object and populate it using the value of the gs and fs register

Parameters:

• fs – value of the fs segment register

• gs – value of the gs segment register

• fs_size – size of the fs segment register

• gs_size – size of the gs segment register

Returns:

gdt a GlobalDescriptorTable object

is_syscall_addr(addr)

prepare_call_state(calling_state, initial_state=None, preserve_registers=(), preserve_memory=())

This function prepares a state that is executing a call instruction. If given an initial_state, it copies over all of the critical registers to it from the calling_state. Otherwise, it prepares the calling_state for action.

This is mostly used to create minimalistic for CFG generation. Some ABIs, such as MIPS PIE and x86 PIE, require certain information to be maintained in certain registers. For example, for PIE MIPS, this function transfer t9, gp, and ra to the new state.

prepare_function_symbol(symbol_name, basic_addr=None)

Prepare the address space with the data necessary to perform relocations pointing to the given symbol

Returns a 2-tuple. The first item is the address of the function code, the second is the address of the relocation target.

setup_gdt(state, gdt)

Write the GlobalDescriptorTable object in the current state memory

Parameters:

• state – state in which to write the GDT

• gdt – GlobalDescriptorTable object

Returns:

state_call(addr, *args, **kwargs)

state_full_init(**kwargs)

syscall(state, allow_unsupported=True)

syscall_abi(state)

Return type:

str

syscall_cc(state)

Return type:

Optional[SimCCSyscall]

syscall_from_addr(addr, allow_unsupported=True)

syscall_from_number(number, allow_unsupported=True, abi=None)

class angr.simos.javavm.SimJavaVM(*args, **kwargs)

Bases: SimOS

__init__(*args, **kwargs)

state_blank(addr=None, **kwargs)

Initialize a blank state.

All parameters are optional.

Parameters:

• addr – The execution start address.

• initial_prefix –

• stack_end – The end of the stack (i.e., the byte after the last valid stack address).

• stack_size – The number of bytes to allocate for stack space

• brk – The address of the process’ break.

Returns:

The initialized SimState.

Any additional arguments will be passed to the SimState constructor

state_entry(args=None, **kwargs)

Create an entry state.

Parameters:

args – List of SootArgument values (optional).

static generate_symbolic_cmd_line_arg(state, max_length=1000)

Generates a new symbolic cmd line argument string. :return: The string reference.

state_call(addr, *args, **kwargs)

Create a native or a Java call state.

Parameters:

• addr – Soot or native addr of the invoke target.

• args – List of SootArgument values.

static get_default_value_by_type(type_, state)

Java specify defaults values for primitive and reference types. This method returns the default value for a given type.

Parameters:

• type (str) – Name of type.

• state (SimState) – Current SimState.

Returns:

Default value for this type.

static cast_primitive(state, value, to_type)

Cast the value of primtive types.

Parameters:

• value – Bitvector storing the primitive value.

• to_type – Name of the targeted type.

Returns:

Resized value.

static init_static_field(state, field_class_name, field_name, field_type)

Initialize the static field with an allocated, but not initialized, object of the given type.

Parameters:

• state – State associated to the field.

• field_class_name – Class containing the field.

• field_name – Name of the field.

• field_type – Type of the field and the new object.

static get_cmd_line_args(state)

get_addr_of_native_method(soot_method)

Get address of the implementation from a native declared Java function.

Parameters:

soot_method – Method descriptor of a native declared function.

Returns:

CLE address of the given method.

get_native_type(java_type)

Maps the Java type to a SimTypeReg representation of its native counterpart. This type can be used to indicate the (well-defined) size of native JNI types.

Returns:

A SymTypeReg with the JNI size of the given type.

get_method_native_type(method)

property native_arch

Arch of the native simos.

Type:

return

get_native_cc()

Returns:

SimCC object for the native simos.

configure_project()

Configure the project to set up global settings (like SimProcedures).

generate_gdt(fs, gs, fs_size=4294967295, gs_size=4294967295)

Generate a GlobalDescriptorTable object and populate it using the value of the gs and fs register

Parameters:

• fs – value of the fs segment register

• gs – value of the gs segment register

• fs_size – size of the fs segment register

• gs_size – size of the gs segment register

Returns:

gdt a GlobalDescriptorTable object

handle_exception(successors, engine, exception)

Perform exception handling. This method will be called when, during execution, a SimException is thrown. Currently, this can only indicate a segfault, but in the future it could indicate any unexpected exceptional behavior that can’t be handled by ordinary control flow.

The method may mutate the provided SimSuccessors object in any way it likes, or re-raise the exception.

Parameters:

• successors – The SimSuccessors object currently being executed on

• engine – The engine that was processing this step

• exception – The actual exception object

is_syscall_addr(addr)

prepare_call_state(calling_state, initial_state=None, preserve_registers=(), preserve_memory=())

This function prepares a state that is executing a call instruction. If given an initial_state, it copies over all of the critical registers to it from the calling_state. Otherwise, it prepares the calling_state for action.

This is mostly used to create minimalistic for CFG generation. Some ABIs, such as MIPS PIE and x86 PIE, require certain information to be maintained in certain registers. For example, for PIE MIPS, this function transfer t9, gp, and ra to the new state.

prepare_function_symbol(symbol_name, basic_addr=None)

Prepare the address space with the data necessary to perform relocations pointing to the given symbol

Returns a 2-tuple. The first item is the address of the function code, the second is the address of the relocation target.

setup_gdt(state, gdt)

Write the GlobalDescriptorTable object in the current state memory

Parameters:

• state – state in which to write the GDT

• gdt – GlobalDescriptorTable object

Returns:

state_full_init(**kwargs)

syscall(state, allow_unsupported=True)

syscall_abi(state)

Return type:

str

syscall_cc(state)

Return type:

Optional[SimCCSyscall]

syscall_from_addr(addr, allow_unsupported=True)

syscall_from_number(number, allow_unsupported=True, abi=None)

angr.simos.javavm.prepare_native_return_state(native_state)

Hook target for native function call returns.

Recovers and stores the return value from native memory and toggles the state, s.t. execution continues in the Soot engine.

Note: Redirection needed for pickling.

Function Signature Matching

class angr.flirt.FlirtSignature(arch, platform, sig_name, sig_path, unique_strings=None, compiler=None, compiler_version=None, os_name=None, os_version=None)

Bases: object

This class describes a FLIRT signature.

Parameters:

• arch (str) –

• platform (str) –

• sig_name (str) –

• sig_path (str) –

• unique_strings (Set[str] | None) –

• compiler (str | None) –

• compiler_version (str | None) –

• os_name (str | None) –

• os_version (str | None) –

__init__(arch, platform, sig_name, sig_path, unique_strings=None, compiler=None, compiler_version=None, os_name=None, os_version=None)

Parameters:

• arch (str) –

• platform (str) –

• sig_name (str) –

• sig_path (str) –

• unique_strings (Set[str] | None) –

• compiler (str | None) –

• compiler_version (str | None) –

• os_name (str | None) –

• os_version (str | None) –

angr.flirt.FS

alias of FlirtSignature

angr.flirt.load_signatures(path)

Recursively load all FLIRT signatures under a specific path.

Parameters:

path (str) – Location of FLIRT signatures.

Return type:

None

angr.flirt.build_sig.get_basic_info(ar_path)

Get basic information of the archive file.

Return type:

Dict[str, str]

Parameters:

ar_path (str) –

angr.flirt.build_sig.get_unique_strings(ar_path)

For Linux libraries, this method requires ar (from binutils), nm (from binutils), and strings.

Return type:

List[str]

Parameters:

ar_path (str) –

angr.flirt.build_sig.run_pelf(pelf_path, ar_path, output_path)

Parameters:

• pelf_path (str) –

• ar_path (str) –

• output_path (str) –

angr.flirt.build_sig.run_sigmake(sigmake_path, sig_name, pat_path, sig_path)

Parameters:

• sigmake_path (str) –

• sig_name (str) –

• pat_path (str) –

• sig_path (str) –

angr.flirt.build_sig.process_exc_file(exc_path)

We are doing the stupidest thing possible: For each batch of conflicts, we pick the most likely result baed on a set of predefined rules.

TODO: Add caller-callee-based de-duplication.

Parameters:

exc_path (str) –

angr.flirt.build_sig.main()

Utils

angr.utils.looks_like_sql(s)

Determine if string s looks like an SQL query.

Parameters:

s (str) – The string to detect.

Return type:

bool

Returns:

True if the string looks like an SQL, False otherwise.

angr.utils.algo.binary_insert(lst, elem, key, lo=0, hi=None)

Insert an element into a sorted list, and keep the list sorted.

The major difference from bisect.bisect_left is that this function supports a key method, so user doesn’t have to create the key array for each insertion.

Parameters:

• lst (list) – The list. Must be pre-ordered.

• element (object) – An element to insert into the list.

• key (func) – A method to get the key for each element in the list.

• lo (int) – Lower bound of the search.

• hi (int) – Upper bound of the search.

• elem (Any) –

Return type:

None

Returns:

None

angr.utils.constants.is_alignment_mask(n)

class angr.utils.cowdict.ChainMapCOW(*args, collapse_threshold=None)

Bases: ChainMap

Implements a copy-on-write version of ChainMap that supports auto-collapsing.

__init__(*args, collapse_threshold=None)

Initialize a ChainMap by setting maps to the given mappings. If no mappings are provided, a single empty dictionary is used.

copy()

New ChainMap or subclass with a new copy of maps[0] and refs to maps[1:]

clean()

clear()

Clear maps[0], leaving maps[1:] intact.

classmethod fromkeys(iterable, *args)

Create a ChainMap with a single dict created from the iterable.

get(k[, d]) → D[k] if k in D, else d.  d defaults to None.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

new_child(m=None)

New ChainMap with a new map followed by all previous maps. If no map is provided, an empty dict is used.

property parents

].

Type:

New ChainMap from maps[1

pop(key, *args)

Remove key from maps[0] and return its value. Raise KeyError if key not in maps[0].

popitem()

Remove and return an item pair from maps[0]. Raise KeyError is maps[0] is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

update([E, ]**F) → None.  Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → an object providing a view on D's values

class angr.utils.cowdict.DefaultChainMapCOW(default_factory, *args, collapse_threshold=None)

Bases: ChainMapCOW

Implements a copy-on-write version of ChainMap with default values that supports auto-collapsing.

__init__(default_factory, *args, collapse_threshold=None)

Initialize a ChainMap by setting maps to the given mappings. If no mappings are provided, a single empty dictionary is used.

clean()

clear()

Clear maps[0], leaving maps[1:] intact.

copy()

New ChainMap or subclass with a new copy of maps[0] and refs to maps[1:]

classmethod fromkeys(iterable, *args)

Create a ChainMap with a single dict created from the iterable.

get(k[, d]) → D[k] if k in D, else d.  d defaults to None.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

new_child(m=None)

New ChainMap with a new map followed by all previous maps. If no map is provided, an empty dict is used.

property parents

].

Type:

New ChainMap from maps[1

pop(key, *args)

Remove key from maps[0] and return its value. Raise KeyError if key not in maps[0].

popitem()

Remove and return an item pair from maps[0]. Raise KeyError is maps[0] is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

update([E, ]**F) → None.  Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → an object providing a view on D's values

class angr.utils.dynamic_dictlist.DynamicDictList(max_size=None, content=None)

Bases: Generic[VT]

A list-like container class that internally uses dicts to store values when the number of values is less than the threshold LIST2DICT_THRESHOLD. Keys must be ints.

The default thresholds are determined according to experiments described at https://github.com/angr/angr/pull/3471#issuecomment-1236515950.

__init__(max_size=None, content=None)

Parameters:

• max_size (int | None) –

• content (DynamicDictList | Dict[int, VT] | List[VT] | None) –

list_content: Optional[List[TypeVar(VT)]]

max_size

dict_content: Optional[Dict[int, TypeVar(VT)]]

real_length()

Return type:

int

angr.utils.enums_conv.cfg_jumpkind_to_pb(jk)

angr.utils.enums_conv.func_edge_type_to_pb(jk)

angr.utils.enums_conv.cfg_jumpkind_from_pb(pb)

angr.utils.enums_conv.func_edge_type_from_pb(pb)

angr.utils.env.is_pyinstaller()

Detect if we are currently running as a PyInstaller-packaged program.

Return type:

bool

Returns:

True if we are running as a PyInstaller-packaged program. False if we are running in Python directly (e.g., development mode).

angr.utils.graph.shallow_reverse(g)

Make a shallow copy of a directional graph and reverse the edges. This is a workaround to solve the issue that one cannot easily make a shallow reversed copy of a graph in NetworkX 2, since networkx.reverse(copy=False) now returns a GraphView, and GraphViews are always read-only.

Parameters:

g (networkx.DiGraph) – The graph to reverse.

Return type:

DiGraph

Returns:

A new networkx.DiGraph that has all nodes and all edges of the original graph, with edges reversed.

angr.utils.graph.inverted_idoms(graph)

Invert the given graph and generate the immediate dominator tree on the inverted graph. This is useful for computing post-dominators.

Parameters:

graph (DiGraph) – The graph to invert and generate immediate dominator tree for.

Return type:

Tuple[DiGraph, Optional[Dict]]

Returns:

A tuple of the inverted graph and the immediate dominator tree.

angr.utils.graph.to_acyclic_graph(graph, ordered_nodes=None, loop_heads=None)

Convert a given DiGraph into an acyclic graph.

Parameters:

• graph (DiGraph) – The graph to convert.

• ordered_nodes (Optional[List]) – A list of nodes sorted in a topological order.

• loop_heads (Optional[List]) – A list of known loop head nodes.

Return type:

DiGraph

Returns:

The converted acyclic graph.

angr.utils.graph.dfs_back_edges(graph, start_node)

Do a DFS traversal of the graph, and return with the back edges.

Note: This is just a naive recursive implementation, feel free to replace it. I couldn’t find anything in networkx to do this functionality. Although the name suggest it, but dfs_labeled_edges is doing something different.

Parameters:

• graph – The graph to traverse.

• start_node – The node where to start the traversal

Returns:

An iterator of ‘backward’ edges

angr.utils.graph.subgraph_between_nodes(graph, source, frontier, include_frontier=False)

For a directed graph, return a subgraph that includes all nodes going from a source node to a target node.

Parameters:

• graph (networkx.DiGraph) – The directed graph.

• source – The source node.

• frontier (list) – A collection of target nodes.

• include_frontier (bool) – Should nodes in frontier be included in the subgraph.

Returns:

A subgraph.

Return type:

networkx.DiGraph

angr.utils.graph.dominates(idom, dominator_node, node)

angr.utils.graph.compute_dominance_frontier(graph, domtree)

Compute a dominance frontier based on the given post-dominator tree.

This implementation is based on figure 2 of paper An Efficient Method of Computing Static Single Assignment Form by Ron Cytron, etc.

Parameters:

• graph – The graph where we want to compute the dominance frontier.

• domtree – The dominator tree

Returns:

A dict of dominance frontier

class angr.utils.graph.TemporaryNode(label)

Bases: object

A temporary node.

Used as the start node and end node in post-dominator tree generation. Also used in some test cases.

__init__(label)

class angr.utils.graph.ContainerNode(obj)

Bases: object

A container node.

Only used in dominator tree generation. We did this so we can set the index property without modifying the original object.

__init__(obj)

index

property obj

class angr.utils.graph.Dominators(graph, entry_node, successors_func=None, reverse=False)

Bases: object

Describes dominators in a graph.

__init__(graph, entry_node, successors_func=None, reverse=False)

dom: DiGraph

class angr.utils.graph.PostDominators(graph, entry_node, successors_func=None)

Bases: Dominators

Describe post-dominators in a graph.

__init__(graph, entry_node, successors_func=None)

property post_dom: DiGraph

dom: DiGraph

class angr.utils.graph.SCCPlaceholder(scc_id)

Bases: object

Describes a placeholder for strongly-connected-components in a graph.

__init__(scc_id)

scc_id

class angr.utils.graph.GraphUtils

Bases: object

A helper class with some static methods and algorithms implemented, that in fact, might take more than just normal CFGs.

static find_merge_points(function_addr, function_endpoints, graph)

Given a local transition graph of a function, find all merge points inside, and then perform a quasi-topological sort of those merge points.

A merge point might be one of the following cases: - two or more paths come together, and ends at the same address. - end of the current function

Parameters:

• function_addr (int) – Address of the function.

• function_endpoints (list) – Endpoints of the function. They typically come from Function.endpoints.

• graph (networkx.DiGraph) – A local transition graph of a function. Normally it comes from Function.graph.

Returns:

A list of ordered addresses of merge points.

Return type:

list

static find_widening_points(function_addr, function_endpoints, graph)

Given a local transition graph of a function, find all widening points inside.

Correctly choosing widening points is very important in order to not lose too much information during static analysis. We mainly consider merge points that has at least one loop back edges coming in as widening points.

Parameters:

• function_addr (int) – Address of the function.

• function_endpoints (list) – Endpoints of the function, typically coming from Function.endpoints.

• graph (networkx.DiGraph) – A local transition graph of a function, normally Function.graph.

Returns:

A list of addresses of widening points.

Return type:

list

static reverse_post_order_sort_nodes(graph, nodes=None)

Sort a given set of nodes in reverse post ordering.

Parameters:

• graph (networkx.DiGraph) – A local transition graph of a function.

• nodes (iterable) – A collection of nodes to sort.

Returns:

A list of sorted nodes.

Return type:

list

static quasi_topological_sort_nodes(graph, nodes=None, loop_heads=None)

Sort a given set of nodes from a graph based on the following rules:

# - if A -> B and not B -> A, then we have A < B # - if A -> B and B -> A, then the ordering is undefined

Following the above rules gives us a quasi-topological sorting of nodes in the graph. It also works for cyclic graphs.

Parameters:

• graph (DiGraph) – A local transition graph of the function.

• nodes (Optional[List]) – A list of nodes to sort. None if you want to sort all nodes inside the graph.

• loop_heads (Optional[List]) – A list of nodes that should be treated loop heads.

Return type:

List

Returns:

A list of ordered nodes.

angr.utils.lazy_import.lazy_import(name)

angr.utils.loader.is_pc(project, ins_addr, addr)

Check if the given address is program counter (PC) or not. This function is for handling the case on some bizarre architectures where PC is always the currently executed instruction address plus a constant value.

Parameters:

• project (Project) – An angr Project instance.

• ins_addr (int) – The address of an instruction. We calculate PC using this instruction address.

• addr (int) – The address to check against.

Return type:

bool

Returns:

True if the given instruction address is the PC, False otherwise.

angr.utils.loader.is_in_readonly_section(project, addr)

Check if the specified address is inside a read-only section.

Parameters:

• project (Project) – An angr Project instance.

• addr (int) – The address to check.

Return type:

bool

Returns:

True if the given address belongs to a read-only section, False otherwise.

angr.utils.loader.is_in_readonly_segment(project, addr)

Check if the specified address is inside a read-only segment.

Parameters:

• project (Project) – An angr Project instance.

• addr (int) – The address to check.

Return type:

bool

Returns:

True if the given address belongs to a read-only segment, False otherwise.

angr.utils.library.get_function_name(s)

Get the function name from a C-style function declaration string.

Parameters:

s (str) – A C-style function declaration string.

Returns:

The function name.

Return type:

str

angr.utils.library.register_kernel_types()

angr.utils.library.convert_cproto_to_py(c_decl)

Convert a C-style function declaration string to its corresponding SimTypes-based Python representation.

Parameters:

c_decl (str) – The C-style function declaration string.

Return type:

Tuple[str, SimTypeFunction, str]

Returns:

A tuple of the function name, the prototype, and a string representing the SimType-based Python representation.

angr.utils.library.convert_cppproto_to_py(cpp_decl, with_param_names=False)

Pre-process a C++-style function declaration string to its corresponding SimTypes-based Python representation.

Parameters:

• cpp_decl (str) – The C++-style function declaration string.

• with_param_names (bool) –

Return type:

Tuple[Optional[str], Optional[SimTypeCppFunction], Optional[str]]

Returns:

A tuple of the function name, the prototype, and a string representing the SimType-based Python representation.

angr.utils.library.parsedcprotos2py(parsed_cprotos, fd_spots=frozenset({}), remove_sys_prefix=False)

Parse a list of C function declarations and output to Python code that can be embedded into angr.procedures.definitions.

>>> # parse the list of glibc C prototypes and output to a file
>>> from angr.procedures.definitions import glibc
>>> with open("glibc_protos", "w") as f: f.write(cprotos2py(glibc._libc_c_decls))

Parameters:

parsed_cprotos (List[Tuple[str, SimTypeFunction, str]]) – A list of tuples where each tuple is (function name, parsed C function prototype, the original function declaration).

Return type:

str

Returns:

A Python string.

angr.utils.library.cprotos2py(cprotos, fd_spots=frozenset({}), remove_sys_prefix=False)

Parse a list of C function declarations and output to Python code that can be embedded into angr.procedures.definitions.

>>> # parse the list of glibc C prototypes and output to a file
>>> from angr.procedures.definitions import glibc
>>> with open("glibc_protos", "w") as f: f.write(cprotos2py(glibc._libc_c_decls))

Parameters:

cprotos (List[str]) – A list of C prototype strings.

Return type:

str

Returns:

A Python string.

angr.utils.library.get_cpp_function_name(demangled_name, specialized=True, qualified=True)

angr.utils.timing.timethis(func)

angr.utils.formatting.setup_terminal()

Check if we are running in a TTY. If so, make sure the terminal supports ANSI escape sequences. If not, disable colorized output. Sets global ansi_color_enabled to True if colorized output should be enabled by default.

angr.utils.formatting.ansi_color(s, color)

Colorize string s by wrapping in ANSI escape sequence for given color.

This function does not consider whether escape sequences are functional or not; it is up to the caller to determine if its appropriate. Check global ansi_color_enabled value in this module.

Return type:

str

Parameters:

• s (str) –

• color (str | None) –

angr.utils.formatting.add_edge_to_buffer(buf, ref, start, end, formatter=None, dashed=False, ascii_only=None)

Draw an edge by adding Unicode box and arrow glyphs to beginning of each line in a list of lines.

Parameters:

• buf (Sequence[str]) – Output buffer, used to render formatted edges.

• ref (Sequence[str]) – Reference buffer, used to calculate edge depth.

• start (int) – Start line.

• end (int) – End line, where arrow points.

• formatter (Optional[Callable[[str], str]]) – Optional callback function used to format the edge before writing it to output buffer.

• dashed (bool) – Render edge line dashed instead of solid.

• ascii_only (Optional[bool]) – Render edge using ASCII characters only. If unspecified, guess by stdout encoding.

Returns:

class angr.utils.mp.Closure(f: Callable[[...], None], args: List[Any], kwargs: Dict[str, Any])

Bases: tuple

A pickle-able lambda; note that f, args, and kwargs must be pickleable

Parameters:

• f (Callable[[...], None]) –

• args (List[Any]) –

• kwargs (Dict[str, Any]) –

f: Callable[..., None]

Alias for field number 0

args: List[Any]

Alias for field number 1

kwargs: Dict[str, Any]

Alias for field number 2

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

class angr.utils.mp.Initializer(*, _manual=True)

Bases: object

A singleton class with global state used to initialize a multiprocessing.Process

Parameters:

_manual (bool) –

classmethod get()

A wrapper around init since this class is a singleton

Return type:

Initializer

__init__(*, _manual=True)

Parameters:

_manual (bool) –

register(f, *args, **kwargs)

A shortcut for adding Closures as initializers

Return type:

None

Parameters:

• f (Callable[[...], None]) –

• args (Any) –

• kwargs (Any) –

initialize()

Initialize a multiprocessing.Process Set the current global initalizer to the same state as this initalizer, then calls each initalizer

Return type:

None

angr.utils.mp.mp_context()

Errors

exception angr.errors.AngrError

Bases: Exception

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrValueError

Bases: AngrError, ValueError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrLifterError

Bases: AngrError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrExitError

Bases: AngrError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrPathError

Bases: AngrError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrVaultError

Bases: AngrError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.PathUnreachableError

Bases: AngrPathError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimulationManagerError

Bases: AngrError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrInvalidArgumentError

Bases: AngrError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrSurveyorError

Bases: AngrError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrAnalysisError

Bases: AngrError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrBladeError

Bases: AngrError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrBladeSimProcError

Bases: AngrBladeError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrAnnotatedCFGError

Bases: AngrError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrBackwardSlicingError

Bases: AngrError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrGirlScoutError

Bases: AngrError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrCallableError

Bases: AngrSurveyorError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrCallableMultistateError

Bases: AngrCallableError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrSyscallError

Bases: AngrError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrSimOSError

Bases: AngrError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrAssemblyError

Bases: AngrError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrIncongruencyError

Bases: AngrAnalysisError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrForwardAnalysisError

Bases: AngrError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrSkipJobNotice

Bases: AngrForwardAnalysisError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrDelayJobNotice

Bases: AngrForwardAnalysisError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrJobMergingFailureNotice

Bases: AngrForwardAnalysisError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrJobWideningFailureNotice

Bases: AngrForwardAnalysisError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrCFGError

Bases: AngrError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrVFGError

Bases: AngrError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrVFGRestartAnalysisNotice

Bases: AngrVFGError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrDataGraphError

Bases: AngrAnalysisError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrDDGError

Bases: AngrAnalysisError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrLoopAnalysisError

Bases: AngrAnalysisError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrExplorationTechniqueError

Bases: AngrError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrExplorerError

Bases: AngrExplorationTechniqueError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrDirectorError

Bases: AngrExplorationTechniqueError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrTracerError

Bases: AngrExplorationTechniqueError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrVariableRecoveryError

Bases: AngrAnalysisError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrDBError

Bases: AngrError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrCorruptDBError

Bases: AngrDBError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrIncompatibleDBError

Bases: AngrDBError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.TracerEnvironmentError

Bases: AngrError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimError

Bases: Exception

bbl_addr = None

stmt_idx = None

ins_addr = None

executed_instruction_count = None

guard = None

record_state(state)

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimStateError

Bases: SimError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimMergeError

Bases: SimStateError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimMemoryError

Bases: SimStateError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimMemoryMissingError(missing_addr, missing_size, *args)

Bases: SimMemoryError

__init__(missing_addr, missing_size, *args)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimAbstractMemoryError

Bases: SimMemoryError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimRegionMapError

Bases: SimMemoryError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimMemoryLimitError

Bases: SimMemoryError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimMemoryAddressError

Bases: SimMemoryError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimFastMemoryError

Bases: SimMemoryError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimEventError

Bases: SimStateError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimPosixError

Bases: SimStateError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimFilesystemError

Bases: SimError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimSymbolicFilesystemError

Bases: SimFilesystemError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimFileError

Bases: SimMemoryError, SimFilesystemError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimHeapError

Bases: SimStateError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimUnsupportedError

Bases: SimError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimSolverError

Bases: SimError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimSolverModeError

Bases: SimSolverError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimSolverOptionError

Bases: SimSolverError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimValueError

Bases: SimSolverError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimUnsatError

Bases: SimValueError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimOperationError

Bases: SimError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.UnsupportedIROpError

Bases: SimOperationError, SimUnsupportedError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimExpressionError

Bases: SimError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.UnsupportedIRExprError

Bases: SimExpressionError, SimUnsupportedError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimCCallError

Bases: SimExpressionError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.UnsupportedCCallError

Bases: SimCCallError, SimUnsupportedError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimUninitializedAccessError(expr_type, expr)

Bases: SimExpressionError

__init__(expr_type, expr)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimStatementError

Bases: SimError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.UnsupportedIRStmtError

Bases: SimStatementError, SimUnsupportedError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.UnsupportedDirtyError

Bases: UnsupportedIRStmtError, SimUnsupportedError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimMissingTempError

Bases: SimValueError, IndexError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimEngineError

Bases: SimError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimIRSBError

Bases: SimEngineError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimTranslationError

Bases: SimEngineError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimProcedureError

Bases: SimEngineError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimProcedureArgumentError

Bases: SimProcedureError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimShadowStackError

Bases: SimProcedureError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimFastPathError

Bases: SimEngineError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimIRSBNoDecodeError

Bases: SimIRSBError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrUnsupportedSyscallError

Bases: AngrSyscallError, SimProcedureError, SimUnsupportedError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

angr.errors.UnsupportedSyscallError

alias of AngrUnsupportedSyscallError

exception angr.errors.SimReliftException(state)

Bases: SimEngineError

__init__(state)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimSlicerError

Bases: SimError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimActionError

Bases: SimError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimCCError

Bases: SimError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimUCManagerError

Bases: SimError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimUCManagerAllocationError

Bases: SimUCManagerError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimUnicornUnsupport

Bases: SimError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimUnicornError

Bases: SimError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimUnicornSymbolic

Bases: SimError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimEmptyCallStackError

Bases: SimError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimStateOptionsError

Bases: SimError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimException

Bases: SimError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimSegfaultException(addr, reason, original_addr=None)

Bases: SimException, SimMemoryError

__init__(addr, reason, original_addr=None)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

angr.errors.SimSegfaultError

alias of SimSegfaultException

exception angr.errors.SimZeroDivisionException

Bases: SimException, SimOperationError

__init__(*args, **kwargs)

args

bbl_addr = None

executed_instruction_count = None

guard = None

ins_addr = None

record_state(state)

stmt_idx = None

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.AngrNoPluginError

Bases: AngrError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimConcreteMemoryError

Bases: AngrError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimConcreteRegisterError

Bases: AngrError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.SimConcreteBreakpointError

Bases: AngrError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception angr.errors.UnsupportedNodeTypeError

Bases: AngrError, NotImplementedError

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

Distributed analysis

class angr.distributed.server.Server(project, spill_yard=None, db=None, max_workers=None, max_states=10, staging_max=10, bucketizer=True, recursion_limit=1000, worker_exit_callback=None, techniques=None, add_options=None, remove_options=None)

Bases: object

Server implements the analysis server with a series of control interfaces exposed.

Variables:

• project – An instance of angr.Project.

• spill_yard (str) – A directory to store spilled states.

• db (str) – Path of the database that stores information about spilled states.

• max_workers (int) – Maximum number of workers. Each worker starts a new process.

• max_states (int) – Maximum number of active states for each worker.

• staging_max (int) – Maximum number of inactive states that are kept into memory before spilled onto the disk and potentially be picked up by another worker.

• bucketizer (bool) – Use the Bucketizer exploration strategy.

• _worker_exit_callback – A method that will be called upon the exit of each worker.

__init__(project, spill_yard=None, db=None, max_workers=None, max_states=10, staging_max=10, bucketizer=True, recursion_limit=1000, worker_exit_callback=None, techniques=None, add_options=None, remove_options=None)

inc_active_workers()

dec_active_workers()

stop()

property active_workers

property stopped

on_worker_exit(worker_id, stashes)

run()

class angr.distributed.worker.BadStatesDropper(vault, db)

Bases: ExplorationTechnique

Dumps and drops states that are not “active”.

__init__(vault, db)

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) –

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) –

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) –

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_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) –

class angr.distributed.worker.ExplorationStatusNotifier(server_state)

Bases: ExplorationTechnique

Force the exploration to stop if the server.stop is True.

Parameters:

server_state (Dict) –

__init__(server_state)

Parameters:

server_state (Dict) –

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) –

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) –

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) –

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_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) –

class angr.distributed.worker.Worker(worker_id, server, server_state, recursion_limit=None, techniques=None, add_options=None, remove_options=None)

Bases: object

Worker implements a worker thread/process for conducting a task.

__init__(worker_id, server, server_state, recursion_limit=None, techniques=None, add_options=None, remove_options=None)

start()

run(initializer)

Parameters:

initializer (Initializer) –