angr.procedures.definitions¶

class angr.procedures.definitions.SimTypeCollection¶

Bases: object

A type collection is the mechanism for describing types. Types in a type collection can be referenced using

__init__()¶

set_names(*names)¶

Parameters:: names (str)

add(name, t)¶

Add a type to the collection.

Parameters:

name (str) – Name of the type to add.
t (SimType) – The SimType object to add to the collection.

Return type:

None

get(name, bottom_on_missing=False, memo=None)¶

Get a SimType object from the collection as identified by the name.

Parameters:

name (str) – Name of the type to get.
bottom_on_missing (bool) – Return a SimTypeBottom object if the required type does not exist.
memo (set[str] | None) – A set of names that have been queried in this call chain (to prevent infinite recursion).

Return type:

SimType

Returns:

The SimType object.

init_str()¶

Return type:: str

to_json(types_as_string=False)¶

Return type:: dict[str, Any]
Parameters:: types_as_string (bool)

classmethod from_json(d)¶

Return type:: SimTypeCollection
Parameters:: d (dict[str, Any])

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__()¶

static from_json(d)¶

Return type:: SimLibrary
Parameters:: d (dict[str, Any])

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 (SimLibrary) – 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 (SimTypeFunction) – The prototype of the function as a SimTypeFunction

Return type:

None

set_prototypes(protos)¶

Set the prototypes of many functions

Parameters:: protos (dict[str, SimTypeFunction]) – Dictionary mapping function names to SimTypeFunction objects
Return type:: None

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.
Return type:: tuple[str, SimTypeFunction]
Returns:: A tuple of (function name, function prototype)

add(name, proc_cls, **kwargs)¶

Add a function implementation to 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, deref=False)¶

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.
deref (bool) – True if any SimTypeRefs in the prototype should be dereferenced using library information.

Return type:

SimTypeFunction | None

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

is_returning(name)¶

Check if a function is known to return.

Parameters:: name (str) – The name of the function.
Return type:: bool
Returns:: A bool indicating if the function is known to return or not.

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, deref=False)¶

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.
deref (bool) – True if any SimTypeRefs in the prototype should be dereferenced using library information.

Return type:

SimTypeFunction | None

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

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__()¶

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

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(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, deref=False)¶

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.
deref (bool) – True if any SimTypeRefs in the prototype should be dereferenced using library information.

Return type:

SimTypeFunction | None

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

angr.procedures.definitions.load_type_collections(only=None, skip=None)¶

Return type:: None

angr.procedures.definitions.load_win32_type_collections()¶

Return type:: None

angr.procedures.definitions.load_external_definitions()¶: Load library definitions from specific directories. By default it parses ANGR_EXTERNAL_DEFINITIONS_DIRS as a semicolon separated list of directory paths. Then it loads all .py files in each directory. These .py files should declare SimLibrary() objects and call .set_library_names() to register themselves in angr.SIM_LIBRARIES.

angr.procedures.definitions.load_win32api_definitions()¶

angr.procedures.definitions.load_all_definitions()¶

Submodules

`cgc`
`gnulib`
`libstdcpp`
`linux_kernel`
`linux_loader`
`macho_libsystem`
`msvcr`
`parse_glibc`
`parse_syscalls_from_local_system`
`parse_win32json`
`types_stl`