Python¶

Python void*

The Python bindings manage opaque void* pointers as Capsules. Given a Capsule, there is no easy way to convert it into a raw address and vice versa. To address this limitation, LIEF exposes lief.to_int() and lief.to_ptr() to convert back and forth between raw addresses and pointers.

Utilities¶

lief.to_int(ptr: typing_extensions.CapsuleType) → int¶: Convert an opaque pointer into an address (int)

lief.to_ptr(ptr: int) → typing_extensions.CapsuleType¶: Convert an integer into an opaque pointer (void*)

runtime.enabled = False¶

runtime.platform = 0¶

runtime.arch = 0¶

lief.runtime.modules() → Iterator[lief.runtime.Module | None]¶: Return an iterator over the different modules loaded in the current process

lief.runtime.assemble(address: int, assembly: str, config: lief.assembly.AssemblerConfig) → bytes¶

Assemble the provided assembly code at the specified (absolute) virtual address.

The function returns the generated assembly bytes.

from lief import runtime
code = runtime.assemble(0x7f0011223344, """
xor rax, rbx;
mov rcx, rax;
""")

If you need to configure the assembly engine or to define addresses for symbols, you can provide your own AssemblerConfig instance.

lief.runtime.disassemble(addr: int) → Iterator[lief.assembly.Instruction | None]¶

Start disassembling instructions at the given absolute virtual address.

from lief import runtime
for inst in runtime.disassemble(0x7f0011223344):
    print(inst)

Host¶

class lief.runtime.Host¶

Bases: object

This class represents the current host.

cache_dir = ''¶

config_dir = ''¶

home_dir = ''¶

name = ''¶

tmp_dir = ''¶

Process¶

class lief.runtime.Process¶

Bases: object

This class represents the current process and provides functions to query process-level information.

class EnvVars¶

Bases: object

This structure wraps environment variables

property vars → dict[str, str]¶

arch = 0¶

envs = <lief._lief.runtime.Process.EnvVars object>¶

get_env(key: str) → str | None = <nanobind.nb_func object>¶

page_size = 0¶

pid = -1¶

platform = 0¶

tid = 0¶

Module¶

class lief.runtime.Module¶

Bases: object

This class represents an in-memory module which can be an executable or a library

contains(self, addr: int) → bool¶: Check if the current module contains the given address

dump(self) → bytes¶

dump(self, filepath: str) → bytes

Overloaded function.

dump(self) -> bytes

Return the content of the module as it is currently mapped in memory

dump(self, filepath: str) -> bytes

Same as dump() but also write the content into the file given in parameter

property end → int¶: End address of the module

property imagebase → int¶: Imagebase of the module

property name → str¶: Name of the module (e.g. libc.so.6, kernel32.dll, libsystem_c.dylib)

property path → str¶: Path of the module

property size → int¶: Virtual size of the current module

lief.runtime.module_from_name(name: str) → lief.runtime.Module | None¶: Find the module with the given name

lief.runtime.module_from_path(path: str) → lief.runtime.Module | None¶: Find the module with the given path

lief.runtime.module_from_addr(addr: int) → lief.runtime.Module | None¶: Find the module that encompasses the given virtual address (absolute)

Memory¶

class lief.runtime.Memory¶

Bases: object

This class exposes API to access and manage memory

ANONYMOUS = 2¶

class Chunk(self, addr: typing_extensions.CapsuleType, size: int, permissions: int)¶

class Chunk(self, addr: typing_extensions.CapsuleType, size: int)

class Chunk(self, addr: typing_extensions.CapsuleType)

Bases: object

Represents a contiguous chunk of memory allocated or inspected by the runtime.

property addr → int¶: Returns the start address of the memory chunk

property addr_ptr → typing_extensions.CapsuleType¶: Returns the start address of the memory chunk as an opaque pointer

cache_flush(self) → lief._lief.runtime.Memory.Chunk¶: Flushes the instruction cache for this memory chunk. This should be used when modifying code in memory (e.g., hooking, JIT).

change_permissions(self, permission: int) → lief._lief.runtime.Memory.Chunk¶: Changes the permissions of the memory chunk.

deallocate(self) → lief._lief.ok_error_t¶

is_valid(self) → bool¶

make_ro(self) → lief._lief.runtime.Memory.Chunk¶: Sets the permissions to Read Only.

make_rw(self) → lief._lief.runtime.Memory.Chunk¶: Sets the permissions to Read and Write.

make_rwx(self) → lief._lief.runtime.Memory.Chunk¶: Sets the permissions to read/write/exec

make_rx(self) → lief._lief.runtime.Memory.Chunk¶: Sets the permissions to Read and Execute.

make_x(self) → lief._lief.runtime.Memory.Chunk¶: Sets the permissions to Execute only.

property page_end → int¶: Returns the address of the end of the page containing this chunk.

property page_start → int¶: Returns the address of the start of the page containing this chunk.

property permissions → int¶: Returns the current permissions of the memory chunk.

property size → int¶: Returns the size of the memory chunk in bytes.

EXEC = 4¶

FIXED = 8¶

JIT = 16¶

class MMAP_FLAGS(*values)¶

Bases: IntFlag

Flags used when creating a memory map (mmap).

ANONYMOUS = 2¶

FIXED = 8¶

JIT = 16¶

NONE = 0¶

PRIVATE = 1¶

SHARED = 4¶

NONE = 0¶

class PERM(*values)¶

Bases: IntFlag

EXEC = 4¶

NONE = 0¶

READ = 1¶

WRITE = 2¶

PRIVATE = 1¶

READ = 1¶

SHARED = 4¶

WRITE = 2¶

mmap(size: int, flags: int, permissions: int) → lief.runtime.Memory.Chunk | None = <nanobind.nb_func object>¶

mmap_hint(hint: int, size: int, flags: int, permissions: int) → lief.runtime.Memory.Chunk | None = <nanobind.nb_func object>¶

mprotect(chunk: lief.runtime.Memory.Chunk, flags: int) → lief.ok_error_t = <nanobind.nb_func object>¶

munmap(chunk: lief.runtime.Memory.Chunk) → lief.ok_error_t = <nanobind.nb_func object>¶

perm_str(flags: int) → str = <nanobind.nb_func object>¶

read(addr: int, out: typing_extensions.CapsuleType, size: int) → bytes | None = <nanobind.nb_func object>¶

read_i16(addr: int) → int = <nanobind.nb_func object>¶

read_i32(addr: int) → int = <nanobind.nb_func object>¶

read_i64(addr: int) → int = <nanobind.nb_func object>¶

read_i8(addr: int) → int = <nanobind.nb_func object>¶

read_u16(addr: int) → int = <nanobind.nb_func object>¶

read_u32(addr: int) → int = <nanobind.nb_func object>¶

read_u64(addr: int) → int = <nanobind.nb_func object>¶

read_u8(addr: int) → int = <nanobind.nb_func object>¶

write(buffer: bytes, addr: int) → lief.ok_error_t = <nanobind.nb_func object>¶

write_i16(value: int, addr: int) → lief.ok_error_t = <nanobind.nb_func object>¶

write_i32(value: int, addr: int) → lief.ok_error_t = <nanobind.nb_func object>¶

write_i64(value: int, addr: int) → lief.ok_error_t = <nanobind.nb_func object>¶

write_i8(value: int, addr: int) → lief.ok_error_t = <nanobind.nb_func object>¶

write_u16(value: int, addr: int) → lief.ok_error_t = <nanobind.nb_func object>¶

write_u32(value: int, addr: int) → lief.ok_error_t = <nanobind.nb_func object>¶

write_u64(value: int, addr: int) → lief.ok_error_t = <nanobind.nb_func object>¶

write_u8(value: int, addr: int) → lief.ok_error_t = <nanobind.nb_func object>¶

MemoryLayout¶

class lief.runtime.MemoryLayout¶

Bases: object

This class exposes the memory layout of the current process.

class Region¶

Bases: object

A contiguous range of memory mapped in the current process.

property addr → int¶: Address at which the region starts

contains(self, addr: int) → bool¶: Whether the given address is within this region

property end_addr → int¶: Address at which the region ends

property name → str¶

Name associated with the region: the name or the path of the module mapped at this address (e.g. libc.so.6) or the identifier of a region that is not backed by a file (e.g. [stack], [heap]).

It can be empty for anonymous regions.

property size → int¶: Size of the region

lief.runtime.memory_layout() → Iterator[lief.runtime.MemoryLayout.Region | None]¶: Return an iterator over the memory layout of the current process

Linux¶

Module¶

class lief.runtime.linux.Module¶

Bases: Module

This class exposes a Linux-specific API for a module

dlsym(self, name: str) → typing_extensions.CapsuleType¶: Resolve the symbol with the given name for the current module

from_handle(handle: typing_extensions.CapsuleType) → lief.runtime.linux.Module | None = <nanobind.nb_func object>¶

property handle → typing_extensions.CapsuleType¶

Return the dlopen handle for this library as an opaque pointer.

Return None if the function fails or if the handler can’t be found

parse_from_memory(self) → lief._lief.ELF.Binary | None¶

parse_from_memory(self, config: lief._lief.ELF.ParserConfig) → lief._lief.ELF.Binary | None

Overloaded function.

parse_from_memory(self) -> Optional[lief._lief.ELF.Binary]

Parse the ELF module from memory

parse_from_memory(self, config: lief._lief.ELF.ParserConfig) -> Optional[lief._lief.ELF.Binary]

Parse the ELF module from memory with the given configuration

parse_from_path(self) → lief._lief.ELF.Binary | None¶

parse_from_path(self, config: lief._lief.ELF.ParserConfig) → lief._lief.ELF.Binary | None

Overloaded function.

parse_from_path(self) -> Optional[lief._lief.ELF.Binary]

Parse the ELF module from its path on the filesystem

parse_from_path(self, config: lief._lief.ELF.ParserConfig) -> Optional[lief._lief.ELF.Binary]

Parse the ELF module from its path on the filesystem and given the parser configuration

lief.runtime.linux.dlopen(name: str | os.PathLike) → lief.runtime.linux.Module | None¶: Load the library with the given path or name.

Host¶

class lief.runtime.linux.Host¶

Bases: object

This class exposes Linux-specific host information.

hardware = ''¶

sys_name = ''¶

sys_release = ''¶

sys_version = ''¶

Process¶

class lief.runtime.linux.Process¶

Bases: Process

This class exposes Linux-specific API for the current process.

cmdline = ''¶

glibc_version = ''¶

Android¶

Module¶

class lief.runtime.android.Module¶

Bases: Module

This class exposes an Android-specific API for a module

dlsym(self, name: str) → typing_extensions.CapsuleType¶: Resolve the symbol with the given name for the current module

from_handle(handle: typing_extensions.CapsuleType) → lief.runtime.android.Module | None = <nanobind.nb_func object>¶

property handle → typing_extensions.CapsuleType¶

Return the dlopen handle for this library.

Return a nullptr if the function fails or if the handler can’t be found

parse_from_memory(self) → lief._lief.ELF.Binary | None¶

parse_from_memory(self, config: lief._lief.ELF.ParserConfig) → lief._lief.ELF.Binary | None

Overloaded function.

parse_from_memory(self) -> Optional[lief._lief.ELF.Binary]

Parse the ELF module from memory

parse_from_memory(self, config: lief._lief.ELF.ParserConfig) -> Optional[lief._lief.ELF.Binary]

Parse the ELF module from memory with the given configuration

parse_from_path(self) → lief._lief.ELF.Binary | None¶

parse_from_path(self, config: lief._lief.ELF.ParserConfig) → lief._lief.ELF.Binary | None

Overloaded function.

parse_from_path(self) -> Optional[lief._lief.ELF.Binary]

Parse the ELF module from its path on the filesystem

parse_from_path(self, config: lief._lief.ELF.ParserConfig) -> Optional[lief._lief.ELF.Binary]

Parse the ELF module from its path on the filesystem and given the parser configuration

lief.runtime.android.dlopen(name: str | os.PathLike) → lief.runtime.android.Module | None¶: Load the library with the given path/name

Host¶

class lief.runtime.android.Host¶

Bases: object

This class exposes Android-specific host information.

sdk_version = None¶

Process¶

class lief.runtime.android.Process¶

Bases: Process

This class exposes Android-specific API for the current process.

cmdline = ''¶

get_system_property(name: str) → lief.runtime.android.Property | None = <nanobind.nb_func object>¶

properties = []¶

Property¶

class lief.runtime.android.Property¶

Bases: object

This class represents an Android system property such as ro.boot.hardware.

property name → str¶: Name of the property (e.g. ro.boot.hardware)

property serial → int¶: Serial number of the property.

property value → str¶: Value associated with the property

macOS¶

Module¶

class lief.runtime.osx.Module¶

Bases: Module

This class exposes an OSX-specific API for a module

dlsym(self, name: str) → typing_extensions.CapsuleType¶: Resolve the symbol with the given name for the current module

from_handle(handle: typing_extensions.CapsuleType) → lief.runtime.osx.Module | None = <nanobind.nb_func object>¶

property handle → typing_extensions.CapsuleType¶

Return the dlopen handle for this library as an opaque pointer.

Return None if the function fails or if the handler can’t be found

parse_from_memory(self) → lief._lief.MachO.Binary | None¶

parse_from_memory(self, config: lief._lief.MachO.ParserConfig) → lief._lief.MachO.Binary | None

Overloaded function.

parse_from_memory(self) -> Optional[lief._lief.MachO.Binary]

Parse the Mach-O module from memory

parse_from_memory(self, config: lief._lief.MachO.ParserConfig) -> Optional[lief._lief.MachO.Binary]

Parse the Mach-O module from memory with the given configuration

parse_from_path(self) → lief._lief.MachO.Binary | None¶

parse_from_path(self, config: lief._lief.MachO.ParserConfig) → lief._lief.MachO.Binary | None

Overloaded function.

parse_from_path(self) -> Optional[lief._lief.MachO.Binary]

Parse the Mach-O module from its path on the filesystem

parse_from_path(self, config: lief._lief.MachO.ParserConfig) -> Optional[lief._lief.MachO.Binary]

Parse the Mach-O module from its path on the filesystem and given the parser configuration

Host¶

class lief.runtime.osx.Host¶

Bases: object

This class exposes OSX-specific host information.

is_sip_enabled = True¶

os_version = <lief._lief.runtime.osx.Host.version_t object>¶

os_version_name = ''¶

class version_t(self, major: int, minor: int, patch: int)¶

Bases: object

This class represents a macOS version number (major.minor.patch).

big_sur → lief.runtime.osx.Host.version_t = <nanobind.nb_func object>¶

property major → int¶: Major version number

property minor → int¶: Minor version number

monterey → lief.runtime.osx.Host.version_t = <nanobind.nb_func object>¶

property patch → int¶: Patch version number

sequoia → lief.runtime.osx.Host.version_t = <nanobind.nb_func object>¶

sonoma → lief.runtime.osx.Host.version_t = <nanobind.nb_func object>¶

tahoe → lief.runtime.osx.Host.version_t = <nanobind.nb_func object>¶

ventura → lief.runtime.osx.Host.version_t = <nanobind.nb_func object>¶

Process¶

class lief.runtime.osx.Process¶

Bases: Process

This class exposes OSX-specific API for the current process.

dyld_version = ''¶

Windows¶

Module¶

class lief.runtime.windows.Module¶

Bases: Module

This class exposes a Windows-specific API for a module

dlsym(self, name: str) → typing_extensions.CapsuleType¶: Resolve the symbol with the given name for the current module

from_handle(handle: typing_extensions.CapsuleType) → lief.runtime.windows.Module | None = <nanobind.nb_func object>¶

property handle → typing_extensions.CapsuleType¶

Return the HMODULE handle as an opaque pointer.

Return None if the function fails or if the handler can’t be found

parse_from_memory(self) → lief._lief.PE.Binary | None¶

parse_from_memory(self, config: lief._lief.PE.ParserConfig) → lief._lief.PE.Binary | None

Overloaded function.

parse_from_memory(self) -> Optional[lief._lief.PE.Binary]

Parse the PE module from memory

parse_from_memory(self, config: lief._lief.PE.ParserConfig) -> Optional[lief._lief.PE.Binary]

Parse the PE module from memory with the given configuration

parse_from_path(self) → lief._lief.PE.Binary | None¶

parse_from_path(self, config: lief._lief.PE.ParserConfig) → lief._lief.PE.Binary | None

Overloaded function.

parse_from_path(self) -> Optional[lief._lief.PE.Binary]

Parse the PE module from its path on the filesystem

parse_from_path(self, config: lief._lief.PE.ParserConfig) -> Optional[lief._lief.PE.Binary]

Parse the PE module from its path on the filesystem and given the parser configuration

lief.runtime.windows.dlopen(name: str | os.PathLike) → lief.runtime.windows.Module | None¶: Load the windows library with the given path or name.

lief.runtime.windows.find_module(name: str) → lief.runtime.windows.Module | None¶

Try to get the Module with the given name.

Return None if the module is not found.

if ntdll := lief.runtime.windows.find_module("ntdll.dll"):
    print(ntdll.path)

Note

This function relies on the Windows API GetModuleHandle which is more efficient than the generic implementation lief.runtime.module_from_name().

Host¶

class lief.runtime.windows.Host¶

Bases: object

This class exposes Windows-specific host information.

version = <lief._lief.runtime.windows.Host.version_t object>¶

class version_t(self)¶

class version_t(self, major: int, minor: int, build_number: int)

Bases: object

This class represents a Windows version number.

property build_number → int¶: Build number

property major → int¶: Major version number

property minor → int¶: Minor version number

Injector¶

class lief.runtime.windows.injection_context_t(self)¶

Bases: object

Describes how to spawn a new process and inject a library into it.

property args → str¶: Command-line arguments passed to the spawned process.

property env → dict[str, str]¶: Environment variables to set in the spawned process. If left empty, the current process environment is inherited.

property library → str¶: Absolute path to the library (DLL) that should be injected.

property target_path → str¶: Absolute path to the target executable to spawn.

lief.runtime.windows.inject_spawn(ctx: lief.runtime.windows.injection_context_t) → lief.ok_t | lief.lief_errors¶: Spawn the target described by the given injection context and inject the associated library before the main thread starts executing.

Process¶

class lief.runtime.windows.Process¶

Bases: Process

This class exposes Windows-specific API for the current process.

peb = None¶

PEB¶

class lief.runtime.windows.PEB¶

Bases: object

This class exposes a user-friendly interface over the Process Environment Block (PEB) of the current process.

It can be accessed through lief.runtime.windows.Process.peb.

property atl_thunk_slist_ptr → int¶: Address of the per-process ATL thunk SList (single-linked list).

property atl_thunk_slist_ptr32 → int¶: 32-bit value of the ATL thunk SList pointer.

property being_debugged → bool¶: Whether the current process is being debugged.

property entries → Iterator[lief.runtime.windows.LdrDataTableEntry | None]¶: Iterate over the modules referenced by the loader data of the PEB, in load order, yielding LdrDataTableEntry objects.

property ldr → int¶: Address of the loader data structure (PEB_LDR_DATA) which holds the list of the modules loaded in the current process.

property post_process_init_routine → int¶: Address of the routine called once the process completed its initialization (PostProcessInitRoutine).

property process_parameters → int¶: Address of the process parameters (RTL_USER_PROCESS_PARAMETERS) which holds information such as the command line or the current directory.

property session_id → int¶: Session ID associated with the current process.

LdrDataTableEntry¶

class lief.runtime.windows.LdrDataTableEntry¶

Bases: object

This class exposes a user-friendly interface over a LDR_DATA_TABLE_ENTRY, the structure used by the Windows loader to describe a module loaded in the current process.

These entries can be enumerated through lief.runtime.windows.PEB.entries().

property active_patch_image_base → int | None¶: Base address of the active hot-patch image, if any.

Note
Available on Windows 11 and later.

property base_dll_name → str¶: Base name of the module (BaseDllName), e.g. ntdll.dll.

property base_name_hash_value → int | None¶: Hash of the module’s base name used to index the loader tables

Note
Available on Windows 8 and later.

property check_sum → int | None¶: Image checksum cached by the loader

Note
Available on Windows 10 and later.

property ddag_node → int | None¶: Address of the dependency-graph node of the module (DdagNode).

Note
Available on Windows 8 and later.

property dependent_load_flags → int | None¶: Flags controlling how the statically-linked dependencies of the module are loaded.

Note
Available on Windows 8 and later.

property dll_base → int¶: Base address at which the module is mapped in memory (DllBase).

property entry_point → int¶: Address of the entry point of the module (EntryPoint).

property entry_point_activation_context → int¶: Address of the activation context associated with the module’s entry point.

property flags → int¶: Loader flags describing the state of the module (Flags).

property full_dll_name → str¶: Full path of the module (FullDllName), e.g. C:\Windows\System32\ntdll.dll.

property hot_patch_state → int | None¶: State of the hot-patch engine for this module, as a LDR_HOT_PATCH_STATE value.

Note
Available on Windows 11 and later.

property implicit_path_options → int | None¶: Path-search options implied when the module was resolved

Note
Available on Windows 8 and later.

property load_context → int | None¶: Address of the loader context used while the module is being snapped

Note
Available on Windows 8 and later.

property load_reason → int | None¶: Reason why the module was loaded, as a LDR_DLL_LOAD_REASON value

Note
Available on Windows 8 and later.

property load_time → int | None¶: Time at which the module was loaded.

Note
Available on Windows 8 and later.

property lock → int¶: Address of the per-entry loader lock.

property obsolete_load_count → int¶: Legacy load count of the module (ObsoleteLoadCount). Superseded by reference_count on Windows 8 and later.

property original_base → int | None¶: Preferred base address recorded in the PE headers

Note
Available on Windows 8 and later.

property parent_dll_base → int | None¶: Base address of the module that triggered the load of this one.

Note
Available on Windows 8 and later.

property reference_count → int | None¶: Number of references currently held on the module.

Note
Available on Windows 8 and later.

property signing_level → int | None¶: Signing level of the module’s image, as a SE_SIGNING_LEVEL value

Note
Available on Windows 10 and later.

property size_of_image → int¶: Size (in bytes) of the module’s image in memory (SizeOfImage).

property switch_back_context → int | None¶: Address of the CHPE switch-back context.

Note
Available on Windows 8 and later.

property time_date_stamp → int¶: TimeDateStamp of the module as cached by the loader.

property tls_index → int¶: TLS slot index assigned to the module, or 0 when it has no TLS (TlsIndex).

ARCH¶

class lief.runtime.ARCH(*values)¶

Bases: Enum

ARM64 = 2¶

NONE = 0¶

RISCV64 = 3¶

X86_64 = 1¶

PLATFORMS¶

class lief.runtime.PLATFORMS(*values)¶

Bases: Enum

ANDROID = 3¶

IOS = 5¶

LINUX = 1¶

NONE = 0¶

OSX = 4¶

WINDOWS = 2¶