Loading Interface

class cle.Loader

Bases: object

The loader loads all the objects and exports an abstraction of the memory of the process. What you see here is an address space with loaded and rebased binaries.

__init__(main_binary: str | BinaryIO | Path | Backend, auto_load_libs: bool = True, concrete_target=None, force_load_libs: Iterable[str | BinaryIO | Path] = (), skip_libs: Iterable[str] = (), main_opts: Dict[str, Any] | None = None, lib_opts: Dict[str, Dict[str, Any]] | None = None, ld_path: Iterable[str | Path] = (), use_system_libs: bool = True, ignore_import_version_numbers: bool = True, case_insensitive: bool = False, rebase_granularity: int = 1048576, except_missing_libs: bool = False, aslr: bool = False, perform_relocations: bool = True, load_debug_info: bool = False, page_size: int = 1, preload_libs: Iterable[str | BinaryIO | Path] = (), arch: Arch | str | None = None)

Parameters:

• main_binary (Union[str, BinaryIO, Path, Backend]) – The path to the main binary you’re loading, or a file-like object with the binary in it.

• auto_load_libs (bool) – Whether to automatically load shared libraries that loaded objects depend on.

• load_debug_info (bool) – Whether to automatically parse DWARF data and search for debug symbol files.

• concrete_target – Whether to instantiate a concrete target for a concrete execution of the process. if this is the case we will need to instantiate a SimConcreteEngine that wraps the ConcreteTarget provided by the user.

• force_load_libs (Iterable[Union[str, BinaryIO, Path]]) – A list of libraries to load regardless of if they’re required by a loaded object.

• skip_libs (Iterable[str]) – A list of libraries to never load, even if they’re required by a loaded object.

• main_opts (Optional[Dict[str, Any]]) – A dictionary of options to be used loading the main binary.

• lib_opts (Optional[Dict[str, Dict[str, Any]]]) – A dictionary mapping library names to the dictionaries of options to be used when loading them.

• ld_path (Iterable[Union[str, Path]]) – A list of paths in which we can search for shared libraries.

• use_system_libs (bool) – Whether or not to search the system load path for requested libraries. Default True.

• ignore_import_version_numbers (bool) – Whether libraries with different version numbers in the filename will be considered equivalent, for example libc.so.6 and libc.so.0

• case_insensitive (bool) – If this is set to True, filesystem loads will be done case-insensitively regardless of the case-sensitivity of the underlying filesystem.

• rebase_granularity (int) – The alignment to use for rebasing shared objects

• except_missing_libs (bool) – Throw an exception when a shared library can’t be found.

• aslr (bool) – Load libraries in symbolic address space. Do not use this option.

• page_size (int) – The granularity with which data is mapped into memory. Set to 0x1000 if you are working in an environment where data will always be memory mapped in a page-graunlar way.

• preload_libs (Iterable[Union[str, BinaryIO, Path]]) – Similar to force_load_libs but will provide for symbol resolution, with precedence over any dependencies.

• perform_relocations (bool) –

• arch (Arch | str | None) –

Variables:

• memory (cle.memory.Clemory) – The loaded, rebased, and relocated memory of the program.

• main_object – The object representing the main binary (i.e., the executable).

• shared_objects – A dictionary mapping loaded library names to the objects representing them.

• all_objects – A list containing representations of all the different objects loaded.

• requested_names – A set containing the names of all the different shared libraries that were marked as a dependency by somebody.

• initial_load_objects – A list of all the objects that were loaded as a result of the initial load request.

When reference is made to a dictionary of options, it requires a dictionary with zero or more of the following keys:

• backend : “elf”, “pe”, “mach-o”, “blob” : which loader backend to use

• arch : The archinfo.Arch object to use for the binary

• base_addr : The address to rebase the object at

• entry_point : The entry point to use for the object

More keys are defined on a per-backend basis.

property main_object: Backend

property memory: Clemory

property tls: ThreadManager

close()

property max_addr: int

The maximum address loaded as part of any loaded object (i.e., the whole address space).

property min_addr: int

The minimum address loaded as part of any loaded object (i.e., the whole address space).

property initializers: List[int]

Return a list of all the initializers that should be run before execution reaches the entry point, in the order they should be run.

property finalizers: List[int]

Return a list of all the finalizers that should be run before the program exits. I’m not sure what order they should be run in.

property linux_loader_object: Backend | None

If the linux dynamic loader is present in memory, return it

property elfcore_object: ELFCore | None

If a corefile was loaded, this returns the actual core object instead of the main binary

property extern_object: ExternObject

Return the extern object used to provide addresses to unresolved symbols and angr internals.

Accessing this property will load this object into memory if it was not previously present.

proposed model for how multiple extern objects should work:

1. extern objects are a linked list. the one in loader._extern_object is the head of the list

2. each round of explicit loads generates a new extern object if it has unresolved dependencies. this object

   has exactly the size necessary to hold all its exports.

3. All requests for size are passed down the chain until they reach an object which has the space to service

   it or an object which has not yet been mapped. If all objects have been mapped and are full, a new extern object is mapped with a fixed size.

property kernel_object: KernelObject

Return the object used to provide addresses to syscalls.

Accessing this property will load this object into memory if it was not previously present.

property all_elf_objects: List[MetaELF]

Return a list of every object that was loaded from an ELF file.

property all_pe_objects: List[PE]

Return a list of every object that was loaded from an ELF file.

property missing_dependencies: Set[str]

Return a set of every name that was requested as a shared object dependency but could not be loaded

property auto_load_libs: bool

describe_addr(addr: int) → str

Returns a textual description of what’s in memory at the provided address

Return type:

str

Parameters:

addr (int) –

find_object(spec: Backend | str, extra_objects: Iterable[Backend] = ()) → Backend | None

If the given library specification has been loaded, return its object, otherwise return None.

Return type:

Optional[Backend]

Parameters:

• spec (Backend | str) –

• extra_objects (Iterable[Backend]) –

find_object_containing(addr: int, membership_check: bool = True) → Backend | None

Return the object that contains the given address, or None if the address is unmapped.

Parameters:

• addr (int) – The address that should be contained in the object.

• membership_check (bool) – Whether a membership check should be performed or not (True by default). This option can be set to False if you are certain that the target object does not have “holes”.

Return type:

Optional[Backend]

Returns:

The object or None.

find_segment_containing(addr: int, skip_pseudo_objects: bool = True) → Segment | None

Find the section object that the address belongs to.

Parameters:

• addr (int) – The address to test

• skip_pseudo_objects (bool) – Skip objects that CLE adds during loading.

Returns:

The section that the address belongs to, or None if the address does not belong to any section, or if section information is not available.

Return type:

cle.Segment

find_section_containing(addr: int, skip_pseudo_objects=True) → Section | None

Find the section object that the address belongs to.

Parameters:

• addr (int) – The address to test.

• skip_pseudo_objects (bool) – Skip objects that CLE adds during loading.

Returns:

The section that the address belongs to, or None if the address does not belong to any section, or if section information is not available.

Return type:

cle.Section

find_loadable_containing(addr: int, skip_pseudo_objects=True) → Region | None

Find the section or segment object the address belongs to. Sections will only be used if the corresponding object does not have segments.

Parameters:

• addr (int) – The address to test

• skip_pseudo_objects – Skip objects that CLE adds during loading.

Return type:

Optional[Region]

Returns:

The section or segment that the address belongs to, or None if the address does not belong to any section or segment.

find_section_next_to(addr: int, skip_pseudo_objects=True) → Section | None

Find the next section after the given address.

Parameters:

• addr (int) – The address to test.

• skip_pseudo_objects (bool) – Skip objects that CLE adds during loading.

Returns:

The next section that goes after the given address, or None if there is no section after the address, or if section information is not available.

Return type:

cle.Section

find_symbol(thing, fuzzy=False) → Symbol | None

Search for the symbol with the given name or address.

Parameters:

• thing – Either the name or address of a symbol to look up

• fuzzy – Set to True to return the first symbol before or at the given address

Return type:

Optional[Symbol]

Returns:

A cle.backends.Symbol object if found, None otherwise.

property symbols: Iterator[Symbol]

find_all_symbols(name: str, exclude_imports=True, exclude_externs=False, exclude_forwards=True) → Iterable[Symbol]

Iterate over all symbols present in the set of loaded binaries that have the given name

Parameters:

• name (str) – The name to search for

• exclude_imports – Whether to exclude import symbols. Default True.

• exclude_externs – Whether to exclude symbols in the extern object. Default False.

• exclude_forwards – Whether to exclude forward symbols. Default True.

Return type:

Iterable[Symbol]

find_plt_stub_name(addr: int) → str | None

Return the name of the PLT stub starting at addr.

Return type:

Optional[str]

Parameters:

addr (int) –

find_relevant_relocations(name: str) → Iterator[Relocation]

Iterate through all the relocations referring to the symbol with the given name

Return type:

Iterator[Relocation]

Parameters:

name (str) –

perform_irelative_relocs(resolver_func)

Use this method to satisfy IRelative relocations in the binary that require execution of loaded code.

Note that this does NOT handle IFunc symbols, which must be handled separately. (this could be changed, but at the moment it’s desirable to support lazy IFunc resolution, since emulation is usually slow)

Parameters:

resolver_func – A callback function that takes an address, runs the code at that address, and returns the return value from the emulated function.

dynamic_load(spec)

Load a file into the address space. Note that the sematics of auto_load_libs and except_missing_libs apply at all times.

Parameters:

spec – The path to the file to load. May be an absolute path, a relative path, or a name to search in the load path.

Returns:

A list of all the objects successfully loaded, which may be empty if this object was previously loaded. If the object specified in spec failed to load for any reason, including the file not being found, return None.

get_loader_symbolic_constraints()

Do not use this method.

fast_memory_load_pointer(addr: int, size: int | None = None) → int | None

Perform a fast memory loading of a pointer.

Parameters:

• addr (int) – Address to read from.

• size (Optional[int]) – Size of the pointer. Default to machine-word size.

Return type:

Optional[int]

Returns:

A pointer or None if the address does not exist.