cle
— Binary Loader¶
CLE is an extensible binary loader. Its main goal is to take an executable program and any libraries it depends on and produce an address space where that program is loaded and ready to run.
The primary interface to CLE is the Loader class.
- class cle.CGC(binary, binary_stream, *args, **kwargs)¶
Bases:
ELF
Backend to support the CGC elf format used by the Cyber Grand Challenge competition.
See : https://github.com/CyberGrandChallenge/libcgcef/blob/master/cgc_executable_format.md
- is_default = True¶
- static is_compatible(stream)¶
- supported_filetypes = ['cgc']¶
- class cle.ELF(*args, addend=None, debug_symbols=None, discard_section_headers=False, discard_program_headers=False, **kwargs)¶
Bases:
MetaELF
The main loader class for statically loading ELF executables. Uses the pyreadelf library where useful.
Useful backend options:
debug_symbols
: Provides the path to a separate file which contains the binary’s debug symbolsdiscard_section_headers
: Do not parse section headers. Use this if they are corrupted or malicious.discard_program_headers
: Do not parse program headers. Use this if the binary is for a platform whose ELFloader only looks at section headers, but whose toolchain generates program headers anyway.
- is_default = True¶
- close()¶
- classmethod check_compatibility(spec, obj)¶
- classmethod check_magic_compatibility(stream)¶
- static is_compatible(stream)¶
- static extract_arch(reader)¶
- property initializers¶
- property finalizers¶
- property symbols_by_name¶
- get_symbol(symid, symbol_table=None)¶
Gets a Symbol object for the specified symbol.
- Parameters:
symid – Either an index into .dynsym or the name of a symbol.
- rebase(new_base)¶
- class cle.PE(*args, **kwargs)¶
Bases:
Backend
Representation of a PE (i.e. Windows) binary.
- is_default = True¶
- static is_compatible(stream)¶
- classmethod check_magic_compatibility(stream)¶
- classmethod check_compatibility(spec, obj)¶
- close()¶
- get_symbol(name)¶
Look up the symbol with the given name. Symbols can be looked up by ordinal with the name
"ordinal.%d" % num
- class cle.XBE(*args, **kwargs)¶
Bases:
Backend
The main loader class for statically loading XBE executables.
- is_default = True¶
- close()¶
- static is_compatible(stream)¶
- property min_addr¶
- property max_addr¶
- classmethod check_compatibility(spec, obj)¶
- class cle.Apk(apk_path, binary_stream, entry_point=None, entry_point_params=(), android_sdk=None, supported_jni_archs=None, jni_libs=None, jni_libs_ld_path=None, **options)¶
Bases:
Soot
Backend for lifting Apk’s to Soot.
- Parameters:
apk_path – Path to APK.
android_sdk – Path to Android SDK folder (e.g. “/home/angr/android/platforms”)
The following parameters are optional
- Parameters:
entry_point – Fully qualified name of method that should be used as the entry point.
supported_jni_archs – List of supported JNI architectures (ABIs) in descending order of preference.
jni_libs – Name(s) of JNI libs to load (if any). If not specified, we try to extract JNI libs from the APK.
jni_libs_ld_path – Path(s) where to find libs defined by param jni_libs. Note: Directory of the APK is added by default.
- is_default = True¶
- get_callbacks(class_name: str, callback_names: List[str]) List[None] ¶
Get callback methods from the name of callback methods.
- Parameters:
class_name – Name of the class.
callback_names – Name list of the callbacks.
- Returns:
The method object which is callback.
- Return type:
list[pysoot.sootir.soot_method.SootMethod]
- static is_compatible(stream)¶
- class cle.BackedCGC(*args, memory_backer=None, register_backer=None, writes_backer=None, permissions_map=None, current_allocation_base=None, **kwargs)¶
Bases:
CGC
This is a backend for CGC executables that allows user provide a memory backer and a register backer as the initial state of the running binary.
- Parameters:
path – File path to CGC executable.
memory_backer – A dict of memory content, with beginning address of each segment as key and actual memory content as data.
register_backer – A dict of all register contents. EIP will be used as the entry point of this executable.
permissions_map – A dict of memory region to permission flags
current_allocation_base – An integer representing the current address of the top of the CGC heap.
- is_default = True¶
- static is_compatible(stream)¶
- property threads¶
- thread_registers(thread=None)¶
- compilation_units: List[CompilationUnit] | None¶
- imports: Dict[str, 'Relocation']¶
- relocs: List[Relocation]¶
- arch: archinfo.Arch | None¶
- exception_handlings: List[ExceptionHandling]¶
- function_hints: List[FunctionHint]¶
- class cle.Backend(binary, binary_stream, loader=None, is_main_bin=False, entry_point=None, arch=None, base_addr=None, force_rebase=False, has_memory=True, **kwargs)¶
Bases:
object
Main base class for CLE binary objects.
An alternate interface to this constructor exists as the static method
cle.loader.Loader.load_object()
- Variables:
binary – The path to the file this object is loaded from
binary_basename – The basename of the filepath, or a short representation of the stream it was loaded from
is_main_bin – Whether this binary is loaded as the main executable
segments – A listing of all the loaded segments in this file
sections – A listing of all the demarked sections in the file
sections_map – A dict mapping from section name to section
imports – A mapping from symbol name to import relocation
resolved_imports – A list of all the import symbols that are successfully resolved
relocs – A list of all the relocations in this binary
irelatives – A list of tuples representing all the irelative relocations that need to be performed. The first item in the tuple is the address of the resolver function, and the second item is the address of where to write the result. The destination address is an RVA.
jmprel – A mapping from symbol name to the address of its jump slot relocation, i.e. its GOT entry.
arch (archinfo.arch.Arch) – The architecture of this binary
os (str) – The operating system this binary is meant to run under
mapped_base (int) – The base address of this object in virtual memory
deps – A list of names of shared libraries this binary depends on
linking – ‘dynamic’ or ‘static’
linked_base – The base address this object requests to be loaded at
pic (bool) – Whether this object is position-independent
execstack (bool) – Whether this executable has an executable stack
provides (str) – The name of the shared library dependancy that this object resolves
symbols (list) – A list of symbols provided by this object, sorted by address
has_memory – Whether this backend is backed by a Clemory or not. As it stands now, a backend should still define min_addr and max_addr even if has_memory is False.
- Parameters:
binary – The path to the binary to load
binary_stream – The open stream to this binary. The reference to this will be held until you call close.
is_main_bin – Whether this binary should be loaded as the main executable
- is_default = False¶
- close()¶
- set_arch(arch)¶
- property image_base_delta¶
- property entry¶
- property sections¶
- property symbols_by_addr¶
- rebase(new_base)¶
Rebase backend’s regions to the new base where they were mapped by the loader
- relocate()¶
Apply all resolved relocations to memory.
The meaning of “resolved relocations” is somewhat subtle - there is a linking step which attempts to resolve each relocation, currently only present in the main internal loading function since the calculation of which objects should be available
- contains_addr(addr)¶
Is addr in one of the binary’s segments/sections we have loaded? (i.e. is it mapped into memory ?)
- find_loadable_containing(addr)¶
- find_segment_containing(addr)¶
Returns the segment that contains addr, or
None
.
- find_section_containing(addr)¶
Returns the section that contains addr or
None
.
- addr_to_offset(addr)¶
- offset_to_addr(offset)¶
- property min_addr¶
This returns the lowest virtual address contained in any loaded segment of the binary.
- property max_addr¶
This returns the highest virtual address contained in any loaded segment of the binary.
- property initializers¶
Stub function. Should be overridden by backends that can provide initializer functions that ought to be run before execution reaches the entry point. Addresses should be rebased.
- property finalizers¶
Stub function. Like initializers, but with finalizers.
- property threads¶
If this backend represents a dump of a running program, it may contain one or more thread contexts, i.e. register files. This property should contain a list of names for these threads, which should be unique.
- thread_registers(thread=None)¶
If this backend represents a dump of a running program, it may contain one or more thread contexts, i.e. register files. This method should return the register file for a given thread (as named in
Backend.threads
) as a dict mapping register names (as seen in archinfo) to numbers. If the thread is not specified, it should return the context for a “default” thread. If there are no threads, it should return an empty dict.
- initial_register_values()¶
Deprecated
- get_symbol(name)¶
Stub function. Implement to find the symbol with name name.
- static extract_soname(path)¶
Extracts the shared object identifier from the path, or returns None if it cannot.
- classmethod is_compatible(stream)¶
Determine quickly whether this backend can load an object from this stream
- classmethod check_compatibility(spec, obj)¶
Performs a minimal static load of
spec
and returns whether it’s compatible with other_obj
- classmethod check_magic_compatibility(stream)¶
Check if a stream of bytes contains the same magic number as the main object
- class cle.Blob(*args, offset=None, segments=None, **kwargs)¶
Bases:
Backend
Representation of a binary blob, i.e. an executable in an unknown file format.
- Parameters:
arch – (required) an
archinfo.Arch
for the binary blob.offset – Skip this many bytes from the beginning of the file.
segments – List of tuples describing how to map data into memory. Tuples are of
(file_offset, mem_addr, size)
.
You can’t specify both
offset
andsegments
.- is_default = True¶
- static is_compatible(stream)¶
- property min_addr¶
- property max_addr¶
- function_name(addr)¶
Blobs don’t support function names.
- contains_addr(addr)¶
- in_which_segment(addr)¶
Blobs don’t support segments.
- classmethod check_compatibility(spec, obj)¶
- imports: Dict[str, 'Relocation']¶
- relocs: List[Relocation]¶
- arch: archinfo.Arch | None¶
- exception_handlings: List[ExceptionHandling]¶
- function_hints: List[FunctionHint]¶
- class cle.ELFCore(*args, executable=None, remote_file_mapping=None, remote_file_mapper=None, **kwargs)¶
Bases:
ELF
Loader class for ELF core files.
One key pain point when analyzing a core dump generated on a remote machine is that the paths to binaries are absolute (and may not exist or be the same on your local machine).
Therefore, you can use the options
`remote_file_mapping
to specify adict
mapping (easy if there are a small number of mappings) orremote_file_mapper
to specify a function that accepts a remote file name and returns the local file name (useful if there are many mappings).If you specify both
remote_file_mapping
andremote_file_mapper
,remote_file_mapping
is applied first, then the result is passed toremote_file_mapper
.- Parameters:
executable – Optional path to the main binary of the core dump. If not supplied, ELFCore will attempt to figure it out automatically from the core dump.
remote_file_mapping – Optional dict that maps specific file names in the core dump to other file names.
remote_file_mapper – Optional function that is used to map every file name in the core dump to whatever is returned from this function.
- is_default = True¶
- static is_compatible(stream)¶
- property threads¶
- thread_registers(thread=None)¶
- compilation_units: List[CompilationUnit] | None¶
- imports: Dict[str, 'Relocation']¶
- relocs: List[Relocation]¶
- arch: archinfo.Arch | None¶
- exception_handlings: List[ExceptionHandling]¶
- function_hints: List[FunctionHint]¶
- class cle.ExceptionHandling(start_addr, size, handler_addr=None, type_=None, func_addr=None)¶
Bases:
object
Describes an exception handling.
Exception handlers are usually language-specific. In C++, it is usually implemented as try {} catch {} blocks.
- Variables:
start_addr (int) – The beginning of the try block.
size (int) – Size of the try block.
handler_addr (Optional[int]) – Address of the exception handler code.
type – Type of the exception handler. Optional.
func_addr (Optional[int]) – Address of the function. Optional.
- start_addr¶
- size¶
- handler_addr¶
- type¶
- func_addr¶
- class cle.FunctionHint(addr, size, source)¶
Bases:
object
Describes a function hint.
- Variables:
addr (int) – Address of the function.
size (int) – Size of the function.
source (int) – Source of this hint.
- addr¶
- size¶
- source¶
- class cle.FunctionHintSource¶
Bases:
object
Enums that describe the source of function hints.
- EH_FRAME = 0¶
- EXTERNAL_EH_FRAME = 1¶
- class cle.Hex(*args, **kwargs)¶
Bases:
Backend
A loader for Intel Hex Objects See https://en.wikipedia.org/wiki/Intel_HEX
- is_default = True¶
- static parse_record(line)¶
- static coalesce_regions(regions)¶
- imports: Dict[str, 'Relocation']¶
- relocs: List[Relocation]¶
- arch: archinfo.Arch | None¶
- exception_handlings: List[ExceptionHandling]¶
- function_hints: List[FunctionHint]¶
- static is_compatible(stream)¶
- class cle.Jar(jar_path, binary_stream, entry_point=None, entry_point_params=('java.lang.String[]',), jni_libs=None, jni_libs_ld_path=None, **kwargs)¶
Bases:
Soot
Backend for lifting JARs to Soot.
- Parameters:
jar_path – Path to JAR.
The following parameters are optional
- Parameters:
entry_point – Fully qualified name of method that should be used as the entry point. If not specified, we try to parse it from the manifest.
additional_jars – Additional JARs.
additional_jar_roots – Additional JAR roots.
jni_libs – Name(s) of JNI libs to load (if any).
jni_libs_ld_path – Path(s) where to find libs defined by param jni_libs. Note: Directory of the JAR is added by default.
- is_default = True¶
- static is_compatible(stream)¶
- get_manifest(binary_path=None)¶
Load the MANIFEST.MF file
- Returns:
A dict of meta info
- Return type:
dict
- imports: Dict[str, 'Relocation']¶
- relocs: List[Relocation]¶
- arch: archinfo.Arch | None¶
- exception_handlings: List[ExceptionHandling]¶
- function_hints: List[FunctionHint]¶
- class cle.MachO(*args, **kwargs)¶
Bases:
Backend
Mach-O binaries for CLE
The Mach-O format is notably different from other formats, as such: * Sections are always part of a segment, self.sections will thus be empty * Symbols cannot be categorized like in ELF * Symbol resolution must be handled by the binary * Rebasing cannot be done statically (i.e. self.mapped_base is ignored for now) * …
- is_default = True¶
- MH_MAGIC_64 = 4277009103¶
- MH_CIGAM_64 = 3489328638¶
- MH_MAGIC = 4277009102¶
- MH_CIGAM = 3472551422¶
- ncmds: int¶
- sizeofcmds: int¶
- classmethod is_compatible(stream)¶
- is_thumb_interworking(address)¶
Returns true if the given address is a THUMB interworking address
- decode_thumb_interworking(address)¶
Decodes a thumb interworking address
- find_segment_by_name(name)¶
- do_binding()¶
- get_string(start)¶
Loads a string from the string table
- parse_lc_str(f, start, limit: int | None = None)¶
Parses a lc_str data structure
- S = ~S¶
- get_symbol_by_address_fuzzy(address)¶
Locates a symbol by checking the given address against sym.addr, sym.bind_xrefs and sym.symbol_stubs
- get_symbol(name, include_stab=False, fuzzy=False)¶
Returns all symbols matching name.
Note that especially when include_stab=True there may be multiple symbols with the same name, therefore this method always returns an array.
- Parameters:
name – the name of the symbol
include_stab – Include debugging symbols NOT RECOMMENDED
fuzzy – Replace exact match with “contains”-style match
- get_symbol_by_insertion_order(idx: int) AbstractMachOSymbol ¶
- Parameters:
idx – idx when this symbol was inserted
- Returns:
- get_segment_by_name(name)¶
Searches for a MachOSegment with the given name and returns it :param name: Name of the sought segment :return: MachOSegment or None
- class cle.MetaELF(*args, **kwargs)¶
Bases:
Backend
A base class that implements functions used by all backends that can load an ELF.
- supported_filetypes = ['elf']¶
- property plt¶
Maps names to addresses.
- property reverse_plt¶
Maps addresses to names.
- property is_ppc64_abiv1¶
Returns whether the arch is PowerPC64 ABIv1.
- Returns:
True if PowerPC64 ABIv1, False otherwise.
- property is_ppc64_abiv2¶
Returns whether the arch is PowerPC64 ABIv2.
- Returns:
True if PowerPC64 ABIv2, False otherwise.
- property ppc64_initial_rtoc¶
Get initial rtoc value for PowerPC64 architecture.
- static extract_soname(path)¶
- imports: Dict[str, 'Relocation']¶
- relocs: List[Relocation]¶
- arch: archinfo.Arch | None¶
- exception_handlings: List[ExceptionHandling]¶
- function_hints: List[FunctionHint]¶
- class cle.Minidump(*args, **kwargs)¶
Bases:
Backend
- is_default = True¶
- close()¶
- static is_compatible(stream)¶
- property threads¶
- thread_registers(thread=None)¶
- imports: Dict[str, 'Relocation']¶
- relocs: List[Relocation]¶
- arch: archinfo.Arch | None¶
- exception_handlings: List[ExceptionHandling]¶
- function_hints: List[FunctionHint]¶
- get_thread_registers_by_id(thread_id)¶
- class cle.NamedRegion(name, start, end, is_readable=True, is_writable=True, is_executable=False, **kwargs)¶
Bases:
Backend
A NamedRegion represents a region of memory that has a name, a location, but no static content.
This region also has permissions; with no memory, these obviously don’t do anything on their own, but they help inform any other code that relies on CLE (e.g., angr)
This can be used as a placeholder for memory that should exist in CLE’s view, but for which it does not need data, like RAM, MMIO, etc
Create a NamedRegion.
- Parameters:
name – The name of the region
start – The start address of the region
end – The end address (exclusive) of the region
is_readable – Whether the region is readable
is_writable – Whether the region is writable
is_executable – Whether the region is executable
kwargs –
- is_default = False¶
- has_memory = False¶
- static is_compatible(stream)¶
- property min_addr¶
- property max_addr¶
- function_name(addr)¶
NamedRegions don’t support function names.
- contains_addr(addr)¶
- classmethod check_compatibility(spec, obj)¶
- imports: Dict[str, 'Relocation']¶
- relocs: List[Relocation]¶
- arch: archinfo.Arch | None¶
- exception_handlings: List[ExceptionHandling]¶
- function_hints: List[FunctionHint]¶
- class cle.Region(offset, vaddr, filesize, memsize)¶
Bases:
object
A region of memory that is mapped in the object’s file.
- Variables:
offset – The offset into the file the region starts.
vaddr – The virtual address.
filesize – The size of the region in the file.
memsize – The size of the region when loaded into memory.
The prefix v- on a variable or parameter name indicates that it refers to the virtual, loaded memory space, while a corresponding variable without the v- refers to the flat zero-based memory of the file.
When used next to each other, addr and offset refer to virtual memory address and file offset, respectively.
- vaddr: int¶
- memsize: int¶
- filesize: int¶
- contains_addr(addr)¶
Does this region contain this virtual address?
- contains_offset(offset)¶
Does this region contain this offset into the file?
- addr_to_offset(addr)¶
Convert a virtual memory address into a file offset
- offset_to_addr(offset)¶
Convert a file offset into a virtual memory address
- property max_addr¶
The maximum virtual address of this region
- property min_addr¶
The minimum virtual address of this region
- property max_offset¶
The maximum file offset of this region
- min_offset()¶
The minimum file offset of this region
- property is_readable: bool¶
- property is_writable: bool¶
- property is_executable: bool¶
- class cle.Regions(lst=None)¶
Bases:
object
A container class acting as a list of regions (sections or segments). Additionally, it keeps an sorted list of all regions that are mapped into memory to allow fast lookups.
We assume none of the regions overlap with others.
- property raw_list: List[Region]¶
Get the internal list. Any change to it is not tracked, and therefore _sorted_list will not be updated. Therefore you probably does not want to modify the list.
- Returns:
The internal list container.
- Return type:
list
- property max_addr: int | None¶
Get the highest address of all regions.
- Returns:
The highest address of all regions, or None if there is no region available.
- Return type:
int or None
- append(region: Region)¶
Append a new Region instance into the list.
- Parameters:
region – The region to append.
- remove(region: Region) None ¶
Remove an existing Region instance from the list.
- Parameters:
region – The region to remove.
- class cle.Section(name, offset, vaddr, size)¶
Bases:
Region
Simple representation of a loaded section.
- Variables:
name (str) – The name of the section
- Parameters:
name (str) – The name of the section
offset (int) – The offset into the binary file this section begins
vaddr (int) – The address in virtual memory this section begins
size (int) – How large this section is
- property is_readable¶
Whether this section has read permissions
- property is_writable¶
Whether this section has write permissions
- property is_executable¶
Whether this section has execute permissions
- vaddr: int¶
- memsize: int¶
- filesize: int¶
- property only_contains_uninitialized_data¶
Whether this section is initialized to zero after the executable is loaded.
- class cle.Segment(offset, vaddr, filesize, memsize)¶
Bases:
Region
- vaddr: int¶
- memsize: int¶
- filesize: int¶
- class cle.Soot(*args, entry_point=None, entry_point_params=(), input_format=None, additional_jars=None, additional_jar_roots=None, jni_libs_ld_path=None, jni_libs=None, android_sdk=None, **kwargs)¶
Bases:
Backend
The basis backend for lifting and loading bytecode from JARs and APKs to Soot IR.
Note that self.min_addr will be 0 and self.max_addr will be 1. Hopefully no other object will be mapped at address 0.
- property max_addr¶
- property entry¶
- property classes¶
- get_soot_class(cls_name, none_if_missing=False)¶
Get Soot class object.
- Parameters:
cls_name (str) – Name of the class.
- Returns:
The class object.
- Return type:
pysoot.soot.SootClass
- get_soot_method(thing, class_name=None, params=(), none_if_missing=False)¶
Get Soot method object.
- Parameters:
thing – Descriptor or the method, or name of the method.
class_name (str) – Name of the class. If not specified, class name can be parsed from method_name.
- Returns:
Soot method that satisfy the criteria.
- property main_methods¶
Find all Main methods in this binary.
- Returns:
All main methods in each class.
- Return type:
iterator
- static is_zip_archive(stream)¶
- imports: Dict[str, 'Relocation']¶
- relocs: List[Relocation]¶
- arch: archinfo.Arch | None¶
- exception_handlings: List[ExceptionHandling]¶
- function_hints: List[FunctionHint]¶
- class cle.StaticArchive(*args, **kwargs)¶
Bases:
Backend
- classmethod is_compatible(stream)¶
- is_default = True¶
- arch: archinfo.Arch | None¶
- imports: Dict[str, 'Relocation']¶
- relocs: List[Relocation]¶
- exception_handlings: List[ExceptionHandling]¶
- function_hints: List[FunctionHint]¶
- cle.register_backend(name, cls)¶
- class cle.ExternObject(loader, map_size=0, tls_size=0)¶
Bases:
Backend
- rebase(new_base)¶
- make_extern(name, size=0, alignment=None, thumb=False, sym_type=SymbolType.TYPE_FUNCTION, point_to=None, libname=None) Symbol ¶
- get_pseudo_addr(name) int ¶
- allocate(size=1, alignment=8, thumb=False, tls=False) int ¶
- property max_addr¶
- make_import(name, sym_type)¶
- imports: Dict[str, 'Relocation']¶
- relocs: List[Relocation]¶
- arch: archinfo.Arch | None¶
- exception_handlings: List[ExceptionHandling]¶
- function_hints: List[FunctionHint]¶
- class cle.ExternSegment(map_size)¶
Bases:
Segment
- addr_to_offset(addr)¶
- offset_to_addr(offset)¶
- contains_offset(offset)¶
- is_readable = True¶
- is_writable = True¶
- is_executable = True¶
- vaddr: int¶
- memsize: int¶
- filesize: int¶
- class cle.KernelObject(loader, map_size=32768)¶
Bases:
Backend
- add_name(name, addr)¶
- property max_addr¶
- imports: Dict[str, 'Relocation']¶
- relocs: List[Relocation]¶
- arch: archinfo.Arch | None¶
- exception_handlings: List[ExceptionHandling]¶
- function_hints: List[FunctionHint]¶
- class cle.PointToPrecise(owner: Backend, name: str, relative_addr: int, size: int, sym_type: SymbolType)¶
Bases:
PointTo
Not documenting this since if you try calling it, you’re wrong.
- pointto_precise = None¶
- relocations()¶
- class cle.TOCRelocation(owner: Backend, symbol: Symbol, relative_addr: int)¶
Bases:
Relocation
- property value¶
- class cle.ELFCoreThreadManager(loader, arch, **kwargs)¶
Bases:
object
- new_thread(insert=False)¶
- register_object(obj)¶
- class cle.ELFThreadManager(*args, **kwargs)¶
Bases:
ThreadManager
- register_object(obj)¶
- class cle.InternalTLSRelocation(val, offset, owner)¶
Bases:
Relocation
- AUTO_HANDLE_NONE = True¶
- property value¶
- class cle.MinidumpThreadManager(loader, arch, **kwargs)¶
Bases:
object
- new_thread(insert=False)¶
- register_object(obj)¶
- class cle.PEThreadManager(loader, arch, max_modules=256)¶
Bases:
ThreadManager
- register_object(obj)¶
- class cle.ThreadManager(loader, arch, max_modules=256)¶
Bases:
object
This class tracks what data is thread-local and can generate thread initialization images
Most of the heavy lifting will be handled in a subclass
- register_object(obj)¶
- static initialization_image(obj) bytes | None ¶
- new_thread(insert=True)¶
- class cle.TLSObject(loader, arch)¶
Bases:
Backend
- imports: Dict[str, 'Relocation']¶
- relocs: List[Relocation]¶
- arch: archinfo.Arch | None¶
- exception_handlings: List[ExceptionHandling]¶
- function_hints: List[FunctionHint]¶
- exception cle.CLECompatibilityError¶
Bases:
CLEError
Error raised when loading an executable that is not currently supported by CLE.
- exception cle.CLEError¶
Bases:
Exception
Base class for errors raised by CLE.
- exception cle.CLEInvalidBinaryError¶
Bases:
CLEError
Error raised when an executable file is invalid or corrupted.
- exception cle.CLEOperationError¶
Bases:
CLEError
Error raised when a problem is encountered in the process of loading an executable.
- exception cle.CLEUnknownFormatError¶
Bases:
CLEError
Error raised when CLE encounters an unknown executable file format.
- cle.convert_info_proc_maps(fname)¶
Convert a dump from gdb’s
info proc maps
command to a set of options that can be passed to CLE to replicate the address space from the gdb session- Parameters:
fname – The name of a file containing the dump
- Returns:
A dict appropriate to be passed as
**kwargs
forangr.Project
orcle.Loader
Convert a dump from gdb’s
info sharedlibrary
command to a set of options that can be passed to CLE to replicate the address space from the gdb session- Parameters:
fname – The name of a file containing the dump
- Returns:
A dict appropriate to be passed as
**kwargs
forangr.Project
orcle.Loader
- class cle.Loader(main_binary, auto_load_libs=True, concrete_target=None, force_load_libs=(), skip_libs=(), main_opts=None, lib_opts=None, ld_path=(), use_system_libs=True, ignore_import_version_numbers=True, case_insensitive=False, rebase_granularity=1048576, except_missing_libs=False, aslr=False, perform_relocations=True, load_debug_info=False, page_size=1, preload_libs=(), arch=None)¶
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.
- Parameters:
main_binary – The path to the main binary you’re loading, or a file-like object with the binary in it.
The following parameters are optional.
- Parameters:
auto_load_libs – Whether to automatically load shared libraries that loaded objects depend on.
load_debug_info – 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 – A list of libraries to load regardless of if they’re required by a loaded object.
skip_libs – A list of libraries to never load, even if they’re required by a loaded object.
main_opts – A dictionary of options to be used loading the main binary.
lib_opts – A dictionary mapping library names to the dictionaries of options to be used when loading them.
ld_path – A list of paths in which we can search for shared libraries.
use_system_libs – Whether or not to search the system load path for requested libraries. Default True.
ignore_import_version_numbers – Whether libraries with different version numbers in the filename will be considered equivalent, for example libc.so.6 and libc.so.0
case_insensitive – If this is set to True, filesystem loads will be done case-insensitively regardless of the case-sensitivity of the underlying filesystem.
rebase_granularity – The alignment to use for rebasing shared objects
except_missing_libs – Throw an exception when a shared library can’t be found.
aslr – Load libraries in symbolic address space. Do not use this option.
page_size – 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 – Similar to force_load_libs but will provide for symbol resolution, with precedence over any dependencies.
- 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.
- tls: ThreadManager | None¶
- close()¶
- property max_addr¶
The maximum address loaded as part of any loaded object (i.e., the whole address space).
- property min_addr¶
The minimum address loaded as part of any loaded object (i.e., the whole address space).
- property initializers¶
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¶
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¶
If the linux dynamic loader is present in memory, return it
- property elfcore_object¶
If a corefile was loaded, this returns the actual core object instead of the main binary
- property extern_object¶
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:
extern objects are a linked list. the one in loader._extern_object is the head of the list
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.
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¶
Return a list of every object that was loaded from an ELF file.
- property all_pe_objects¶
Return a list of every object that was loaded from an ELF file.
- property missing_dependencies¶
Return a set of every name that was requested as a shared object dependency but could not be loaded
- property auto_load_libs¶
- describe_addr(addr) str ¶
Returns a textual description of what’s in memory at the provided address
- find_object(spec, extra_objects=())¶
If the given library specification has been loaded, return its object, otherwise return None.
- find_object_containing(addr, membership_check=True)¶
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”.
- Returns:
The object or None.
- find_segment_containing(addr, skip_pseudo_objects=True)¶
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:
- find_section_containing(addr, skip_pseudo_objects=True)¶
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:
- find_loadable_containing(addr, skip_pseudo_objects=True)¶
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 – The address to test
skip_pseudo_objects – Skip objects that CLE adds during loading.
- 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, skip_pseudo_objects=True)¶
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:
- find_symbol(thing, fuzzy=False)¶
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
- Returns:
A
cle.backends.Symbol
object if found, None otherwise.
- property symbols¶
- find_all_symbols(name, exclude_imports=True, exclude_externs=False, exclude_forwards=True)¶
Iterate over all symbols present in the set of loaded binaries that have the given name
- Parameters:
name – 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.
- find_plt_stub_name(addr)¶
Return the name of the PLT stub starting at
addr
.
- find_relevant_relocations(name)¶
Iterate through all the relocations referring to the symbol with the given
name
- 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
andexcept_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.
- class cle.Clemory(arch, root=False)¶
Bases:
ClemoryBase
An object representing a memory space.
Accesses can be made with [index] notation.
- consecutive¶
- min_addr¶
- max_addr¶
- add_backer(start, data, overwrite=False)¶
Adds a backer to the memory.
- Parameters:
start – The address where the backer should be loaded.
data – The backer itself. Can be either a bytestring or another
Clemory
.overwrite – If True and the range overlaps any existing backer, the existing backer will be split up and the overlapping part will be replaced with the new backer.
- split_backer(addr)¶
Ensures that
addr
is the start of a backer, if it is backed.
- update_backer(start, data)¶
- remove_backer(start)¶
- backers(addr=0)¶
Iterate through each backer for this clemory and all its children, yielding tuples of
(start_addr, backer)
where each backer is a bytearray.- Parameters:
addr – An optional starting address - all backers before and not including this address will be skipped.
- load(addr, n)¶
Read up to n bytes at address addr in memory and return a bytes object.
Reading will stop at the beginning of the first unallocated region found, or when n bytes have been read.
- store(addr, data)¶
Write bytes from data at address addr.
Note: If the store runs off the end of a backer and into unbacked space, this function will update the backer but also raise
KeyError
.
- find(data, search_min=None, search_max=None)¶
Find all occurances of a bytestring in memory.
- Parameters:
data (bytes) – The bytestring to search for
search_min (int) – Optional: The first address to include as valid
search_max (int) – Optional: The last address to include as valid
- Return Iterator[int]:
Iterates over addresses at which the bytestring occurs
- class cle.ClemoryBase(arch)¶
Bases:
object
- load(addr, n)¶
- store(addr, data)¶
- backers(addr=0)¶
- find(data, search_min=None, search_max=None)¶
- unpack(addr, fmt)¶
Use the
struct
module to unpack the data at address addr with the format fmt.
- unpack_word(addr, size=None, signed=False, endness=None)¶
Use the
struct
module to unpack a single integer from the address addr.You may override any of the attributes of the word being extracted:
- Parameters:
size (int) – The size in bytes to pack/unpack. Defaults to wordsize (e.g. 4 bytes on a 32 bit architecture)
signed (bool) – Whether the data should be extracted signed/unsigned. Default unsigned
endness (archinfo.Endness) – The endian to use in packing/unpacking. Defaults to memory endness
- pack(addr, fmt, *data)¶
Use the
struct
module to pack data into memory at address addr with the format fmt.
- pack_word(addr, data, size=None, signed=False, endness=None)¶
Use the
struct
module to pack a single integer data into memory at the address addr.You may override any of the attributes of the word being packed:
- Parameters:
size (int) – The size in bytes to pack/unpack. Defaults to wordsize (e.g. 4 bytes on a 32 bit architecture)
signed (bool) – Whether the data should be extracted signed/unsigned. Default unsigned
endness (archinfo.Endness) – The endian to use in packing/unpacking. Defaults to memory endness
- read(nbytes)¶
The stream-like function that reads up to a number of bytes starting from the current position and updates the current position. Use with
seek()
.Up to nbytes bytes will be read, halting at the beginning of the first unmapped region encountered.
- seek(value)¶
The stream-like function that sets the “file’s” current position. Use with
read()
.- Parameters:
value – The position to seek to.
- tell()¶
- close()¶
- class cle.ClemoryView(backer, start, end, offset=0)¶
Bases:
ClemoryBase
A Clemory which presents a subset of another Clemory as an address space
- Parameters:
backer – The parent clemory to use
start – The address in the parent to start at
end – The address in the parent to end at (exclusive)
offset – Where the address space should start in this Clemory. Default 0.
- backers(addr=0)¶
- load(addr, n)¶
- store(addr, data)¶
- find(data, search_min=None, search_max=None)¶
- class cle.PatchedStream(stream, patches)¶
Bases:
object
An object that wraps a readable stream, performing passthroughs on seek and read operations, except to make it seem like the data has actually been patched by the given patches.
- Parameters:
stream – The stream to patch
patches – A list of tuples of (addr, patch data)
- read(*args, **kwargs)¶
- seek(*args, **kwargs)¶
- tell()¶
- close()¶
- class cle.AddressTranslator(rva, owner)¶
Bases:
object
- Parameters:
rva (int) – virtual address relative to owner’s object image base
owner (cle.Backend) – The object owner address relates to
- classmethod from_lva(lva, owner)¶
Loads address translator with LVA
- classmethod from_mva(mva, owner)¶
Loads address translator with MVA
- classmethod from_rva(rva, owner)¶
Loads address translator with RVA
- classmethod from_raw(raw, owner)¶
Loads address translator with RAW address
- classmethod from_linked_va(lva, owner)¶
Loads address translator with LVA
- classmethod from_va(mva, owner)¶
Loads address translator with MVA
- classmethod from_mapped_va(mva, owner)¶
Loads address translator with MVA
- classmethod from_relative_va(rva, owner)¶
Loads address translator with RVA
- to_lva()¶
VA -> LVA :rtype: int
- to_mva()¶
RVA -> MVA :rtype: int
- to_rva()¶
RVA -> RVA :rtype: int
- to_raw()¶
RVA -> RAW :rtype: int
- to_linked_va()¶
VA -> LVA :rtype: int
- to_va()¶
RVA -> MVA :rtype: int
- to_mapped_va()¶
RVA -> MVA :rtype: int
- to_relative_va()¶
RVA -> RVA :rtype: int
- cle.AT¶
alias of
AddressTranslator
- class cle.Symbol(owner: Backend, name: str, relative_addr: int, size: int, sym_type: SymbolType)¶
Bases:
object
Representation of a symbol from a binary file. Smart enough to rebase itself.
There should never be more than one Symbol instance representing a single symbol. To make sure of this, only use the
cle.backends.Backend.get_symbol()
to create new symbols.- Variables:
owner (cle.backends.Backend) – The object that contains this symbol
name (str) – The name of this symbol
addr (int) – The un-based address of this symbol, an RVA
size (int) – The size of this symbol
_type – The ABI-agnostic type of this symbol
resolved (bool) – Whether this import symbol has been resolved to a real symbol
resolvedby (None or cle.backends.Symbol) – The real symbol this import symbol has been resolve to
resolvewith (str) – The name of the library we must use to resolve this symbol, or None if none is required.
Not documenting this since if you try calling it, you’re wrong.
- resolve(obj)¶
- property type: SymbolType¶
The ABI-agnostic SymbolType. Must be overridden by derived types.
- property subtype: SymbolSubType¶
A subclass’ ABI-specific types
- property rebased_addr¶
The address of this symbol in the global memory space
- property linked_addr¶
- property is_function¶
Whether this symbol is a function
- is_static = False¶
- is_common = False¶
- is_import = False¶
- is_export = False¶
- is_local = False¶
- is_weak = False¶
- is_extern = False¶
- is_forward = False¶
- resolve_forwarder()¶
If this symbol is a forwarding export, return the symbol the forwarding refers to, or None if it cannot be found
- property owner_obj¶
- class cle.SymbolType(value)¶
Bases:
Enum
ABI-agnostic symbol types
- TYPE_OTHER = 0¶
- TYPE_NONE = 1¶
- TYPE_FUNCTION = 2¶
- TYPE_OBJECT = 3¶
- TYPE_SECTION = 4¶
- TYPE_TLS_OBJECT = 5¶
- class cle.SymbolSubType(value)¶
Bases:
Enum
Abstract base class for ABI-specific symbol types
- to_base_type() SymbolType ¶
A subclass’ ABI-specific mapping to :SymbolType:
Loading Interface¶
- class cle.loader.Loader(main_binary, auto_load_libs=True, concrete_target=None, force_load_libs=(), skip_libs=(), main_opts=None, lib_opts=None, ld_path=(), use_system_libs=True, ignore_import_version_numbers=True, case_insensitive=False, rebase_granularity=1048576, except_missing_libs=False, aslr=False, perform_relocations=True, load_debug_info=False, page_size=1, preload_libs=(), arch=None)¶
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.
- Parameters:
main_binary – The path to the main binary you’re loading, or a file-like object with the binary in it.
The following parameters are optional.
- Parameters:
auto_load_libs – Whether to automatically load shared libraries that loaded objects depend on.
load_debug_info – 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 – A list of libraries to load regardless of if they’re required by a loaded object.
skip_libs – A list of libraries to never load, even if they’re required by a loaded object.
main_opts – A dictionary of options to be used loading the main binary.
lib_opts – A dictionary mapping library names to the dictionaries of options to be used when loading them.
ld_path – A list of paths in which we can search for shared libraries.
use_system_libs – Whether or not to search the system load path for requested libraries. Default True.
ignore_import_version_numbers – Whether libraries with different version numbers in the filename will be considered equivalent, for example libc.so.6 and libc.so.0
case_insensitive – If this is set to True, filesystem loads will be done case-insensitively regardless of the case-sensitivity of the underlying filesystem.
rebase_granularity – The alignment to use for rebasing shared objects
except_missing_libs – Throw an exception when a shared library can’t be found.
aslr – Load libraries in symbolic address space. Do not use this option.
page_size – 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 – Similar to force_load_libs but will provide for symbol resolution, with precedence over any dependencies.
- 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.
- tls: ThreadManager | None¶
- close()¶
- property max_addr¶
The maximum address loaded as part of any loaded object (i.e., the whole address space).
- property min_addr¶
The minimum address loaded as part of any loaded object (i.e., the whole address space).
- property initializers¶
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¶
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¶
If the linux dynamic loader is present in memory, return it
- property elfcore_object¶
If a corefile was loaded, this returns the actual core object instead of the main binary
- property extern_object¶
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:
extern objects are a linked list. the one in loader._extern_object is the head of the list
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.
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¶
Return a list of every object that was loaded from an ELF file.
- property all_pe_objects¶
Return a list of every object that was loaded from an ELF file.
- property missing_dependencies¶
Return a set of every name that was requested as a shared object dependency but could not be loaded
- property auto_load_libs¶
- describe_addr(addr) str ¶
Returns a textual description of what’s in memory at the provided address
- find_object(spec, extra_objects=())¶
If the given library specification has been loaded, return its object, otherwise return None.
- find_object_containing(addr, membership_check=True)¶
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”.
- Returns:
The object or None.
- find_segment_containing(addr, skip_pseudo_objects=True)¶
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:
- find_section_containing(addr, skip_pseudo_objects=True)¶
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:
- find_loadable_containing(addr, skip_pseudo_objects=True)¶
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 – The address to test
skip_pseudo_objects – Skip objects that CLE adds during loading.
- 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, skip_pseudo_objects=True)¶
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:
- find_symbol(thing, fuzzy=False)¶
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
- Returns:
A
cle.backends.Symbol
object if found, None otherwise.
- property symbols¶
- find_all_symbols(name, exclude_imports=True, exclude_externs=False, exclude_forwards=True)¶
Iterate over all symbols present in the set of loaded binaries that have the given name
- Parameters:
name – 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.
- find_plt_stub_name(addr)¶
Return the name of the PLT stub starting at
addr
.
- find_relevant_relocations(name)¶
Iterate through all the relocations referring to the symbol with the given
name
- 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
andexcept_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.
Backends¶
- class cle.backends.FunctionHintSource¶
Bases:
object
Enums that describe the source of function hints.
- EH_FRAME = 0¶
- EXTERNAL_EH_FRAME = 1¶
- class cle.backends.FunctionHint(addr, size, source)¶
Bases:
object
Describes a function hint.
- Variables:
addr (int) – Address of the function.
size (int) – Size of the function.
source (int) – Source of this hint.
- addr¶
- size¶
- source¶
- class cle.backends.ExceptionHandling(start_addr, size, handler_addr=None, type_=None, func_addr=None)¶
Bases:
object
Describes an exception handling.
Exception handlers are usually language-specific. In C++, it is usually implemented as try {} catch {} blocks.
- Variables:
start_addr (int) – The beginning of the try block.
size (int) – Size of the try block.
handler_addr (Optional[int]) – Address of the exception handler code.
type – Type of the exception handler. Optional.
func_addr (Optional[int]) – Address of the function. Optional.
- start_addr¶
- size¶
- handler_addr¶
- type¶
- func_addr¶
- class cle.backends.Backend(binary, binary_stream, loader=None, is_main_bin=False, entry_point=None, arch=None, base_addr=None, force_rebase=False, has_memory=True, **kwargs)¶
Bases:
object
Main base class for CLE binary objects.
An alternate interface to this constructor exists as the static method
cle.loader.Loader.load_object()
- Variables:
binary – The path to the file this object is loaded from
binary_basename – The basename of the filepath, or a short representation of the stream it was loaded from
is_main_bin – Whether this binary is loaded as the main executable
segments – A listing of all the loaded segments in this file
sections – A listing of all the demarked sections in the file
sections_map – A dict mapping from section name to section
imports – A mapping from symbol name to import relocation
resolved_imports – A list of all the import symbols that are successfully resolved
relocs – A list of all the relocations in this binary
irelatives – A list of tuples representing all the irelative relocations that need to be performed. The first item in the tuple is the address of the resolver function, and the second item is the address of where to write the result. The destination address is an RVA.
jmprel – A mapping from symbol name to the address of its jump slot relocation, i.e. its GOT entry.
arch (archinfo.arch.Arch) – The architecture of this binary
os (str) – The operating system this binary is meant to run under
mapped_base (int) – The base address of this object in virtual memory
deps – A list of names of shared libraries this binary depends on
linking – ‘dynamic’ or ‘static’
linked_base – The base address this object requests to be loaded at
pic (bool) – Whether this object is position-independent
execstack (bool) – Whether this executable has an executable stack
provides (str) – The name of the shared library dependancy that this object resolves
symbols (list) – A list of symbols provided by this object, sorted by address
has_memory – Whether this backend is backed by a Clemory or not. As it stands now, a backend should still define min_addr and max_addr even if has_memory is False.
- Parameters:
binary – The path to the binary to load
binary_stream – The open stream to this binary. The reference to this will be held until you call close.
is_main_bin – Whether this binary should be loaded as the main executable
- is_default = False¶
- imports: Dict[str, 'Relocation']¶
- relocs: List[Relocation]¶
- exception_handlings: List[ExceptionHandling]¶
- function_hints: List[FunctionHint]¶
- arch: archinfo.Arch | None¶
- close()¶
- set_arch(arch)¶
- property image_base_delta¶
- property entry¶
- property sections¶
- property symbols_by_addr¶
- rebase(new_base)¶
Rebase backend’s regions to the new base where they were mapped by the loader
- relocate()¶
Apply all resolved relocations to memory.
The meaning of “resolved relocations” is somewhat subtle - there is a linking step which attempts to resolve each relocation, currently only present in the main internal loading function since the calculation of which objects should be available
- contains_addr(addr)¶
Is addr in one of the binary’s segments/sections we have loaded? (i.e. is it mapped into memory ?)
- find_loadable_containing(addr)¶
- find_segment_containing(addr)¶
Returns the segment that contains addr, or
None
.
- find_section_containing(addr)¶
Returns the section that contains addr or
None
.
- addr_to_offset(addr)¶
- offset_to_addr(offset)¶
- property min_addr¶
This returns the lowest virtual address contained in any loaded segment of the binary.
- property max_addr¶
This returns the highest virtual address contained in any loaded segment of the binary.
- property initializers¶
Stub function. Should be overridden by backends that can provide initializer functions that ought to be run before execution reaches the entry point. Addresses should be rebased.
- property finalizers¶
Stub function. Like initializers, but with finalizers.
- property threads¶
If this backend represents a dump of a running program, it may contain one or more thread contexts, i.e. register files. This property should contain a list of names for these threads, which should be unique.
- thread_registers(thread=None)¶
If this backend represents a dump of a running program, it may contain one or more thread contexts, i.e. register files. This method should return the register file for a given thread (as named in
Backend.threads
) as a dict mapping register names (as seen in archinfo) to numbers. If the thread is not specified, it should return the context for a “default” thread. If there are no threads, it should return an empty dict.
- initial_register_values()¶
Deprecated
- get_symbol(name)¶
Stub function. Implement to find the symbol with name name.
- static extract_soname(path)¶
Extracts the shared object identifier from the path, or returns None if it cannot.
- classmethod is_compatible(stream)¶
Determine quickly whether this backend can load an object from this stream
- classmethod check_compatibility(spec, obj)¶
Performs a minimal static load of
spec
and returns whether it’s compatible with other_obj
- classmethod check_magic_compatibility(stream)¶
Check if a stream of bytes contains the same magic number as the main object
- cle.backends.register_backend(name, cls)¶
- class cle.backends.ELF(*args, addend=None, debug_symbols=None, discard_section_headers=False, discard_program_headers=False, **kwargs)¶
Bases:
MetaELF
The main loader class for statically loading ELF executables. Uses the pyreadelf library where useful.
Useful backend options:
debug_symbols
: Provides the path to a separate file which contains the binary’s debug symbolsdiscard_section_headers
: Do not parse section headers. Use this if they are corrupted or malicious.discard_program_headers
: Do not parse program headers. Use this if the binary is for a platform whose ELFloader only looks at section headers, but whose toolchain generates program headers anyway.
- is_default = True¶
- imports: Dict[str, 'Relocation']¶
- relocs: List[Relocation]¶
- compilation_units: List[CompilationUnit] | None¶
- close()¶
- classmethod check_compatibility(spec, obj)¶
- classmethod check_magic_compatibility(stream)¶
- static is_compatible(stream)¶
- static extract_arch(reader)¶
- property initializers¶
- property finalizers¶
- property symbols_by_name¶
- get_symbol(symid, symbol_table=None)¶
Gets a Symbol object for the specified symbol.
- Parameters:
symid – Either an index into .dynsym or the name of a symbol.
- rebase(new_base)¶
- arch: archinfo.Arch | None¶
- exception_handlings: List[ExceptionHandling]¶
- function_hints: List[FunctionHint]¶
- class cle.backends.ELFCore(*args, executable=None, remote_file_mapping=None, remote_file_mapper=None, **kwargs)¶
Bases:
ELF
Loader class for ELF core files.
One key pain point when analyzing a core dump generated on a remote machine is that the paths to binaries are absolute (and may not exist or be the same on your local machine).
Therefore, you can use the options
`remote_file_mapping
to specify adict
mapping (easy if there are a small number of mappings) orremote_file_mapper
to specify a function that accepts a remote file name and returns the local file name (useful if there are many mappings).If you specify both
remote_file_mapping
andremote_file_mapper
,remote_file_mapping
is applied first, then the result is passed toremote_file_mapper
.- Parameters:
executable – Optional path to the main binary of the core dump. If not supplied, ELFCore will attempt to figure it out automatically from the core dump.
remote_file_mapping – Optional dict that maps specific file names in the core dump to other file names.
remote_file_mapper – Optional function that is used to map every file name in the core dump to whatever is returned from this function.
- is_default = True¶
- static is_compatible(stream)¶
- property threads¶
- thread_registers(thread=None)¶
- compilation_units: List[CompilationUnit] | None¶
- imports: Dict[str, 'Relocation']¶
- relocs: List[Relocation]¶
- arch: archinfo.Arch | None¶
- exception_handlings: List[ExceptionHandling]¶
- function_hints: List[FunctionHint]¶