angr.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 (bytes | str) – 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

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.

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

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.

__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, cache_limits=None, rustc_version=None, rustc_optimization_level=None, **kwargs)
Parameters:

  • load_options (dict[str, Any] | None)

  • selfmodifying_code (bool)

  • support_selfmodifying_code (bool | None)

  • cache_limits (dict[str, int | None] | None)

arch: Arch
property llm_client

The LLM client for this project. Lazy-initialized from environment variables on first access. Set manually via project.llm_client = LLMClient(...) or configure via environment variables ANGR_LLM_MODEL, ANGR_LLM_API_KEY, ANGR_LLM_API_BASE.

property kb
get_kb(name)
property 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 (bool | None) – 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:

SimProcedure | None

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 (bool | None) – 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:

SimProcedure | None

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

languages()
Return type:

list[str]

property is_rust_binary: bool
get_function_cache_limit()

Get the cache limit for function-level caches.

Return type:

int | None

Returns:

The cache limit, or None for disabling the cache.

get_cfg_node_cache_limit()

Get the cache limit for CFG node caches.

Return type:

int | None

Returns:

The cache limit, or None to disable the cache.

get_cfg_edge_cache_limit()

Get the cache limit for CFG edge caches (adjacency data spilling).

Return type:

int | None

Returns:

The cache limit, or None to disable the cache.