0
# LIEF
1

2
LIEF (Library to Instrument Executable Formats) is a comprehensive cross-platform library for parsing, modifying, and abstracting executable file formats. It provides unified APIs to analyze and manipulate ELF, PE, Mach-O, and Android formats (DEX, ART, OAT, VDEX), along with advanced features like disassembly, debug information extraction, and format conversion.
3

4
## Package Information
5

6
- **Package Name**: lief
7
- **Package Type**: PyPI
8
- **Language**: Python (with C++ backend)
9
- **Installation**: `pip install lief`
10

11
## Core Imports
12

13
```python
14
import lief
15
from typing import Union, Optional, Iterator, List, Sequence
16
import io
17
import os
18
```
19

20
For format-specific operations:
21

22
```python
23
import lief.ELF
24
import lief.PE  
25
import lief.MachO
26
import lief.Android
27
# Android-specific formats
28
import lief.DEX
29
import lief.ART
30
import lief.OAT
31
import lief.VDEX
32
```
33

34
For extended features:
35

36
```python
37
import lief.assembly
38
import lief.dwarf
39
import lief.pdb
40
import lief.objc
41
import lief.dsc
42
```
43

44
## Basic Usage
45

46
```python
47
import lief
48

49
# Parse any supported binary format
50
binary = lief.parse("/path/to/binary")
51

52
if binary is None:
53
    print("Unable to parse binary")
54
    exit(1)
55

56
# Access common properties across all formats
57
print(f"Format: {binary.format}")
58
print(f"Architecture: {binary.header.architecture}")
59
print(f"Entry point: 0x{binary.entrypoint:x}")
60
print(f"Is PIE: {binary.is_pie}")
61

62
# Iterate through sections
63
for section in binary.sections:
64
    print(f"Section: {section.name} - Size: {section.size}")
65

66
# Find symbols
67
if binary.has_symbol("main"):
68
    main_symbol = binary.get_symbol("main")
69
    print(f"Main function at: 0x{main_symbol.value:x}")
70

71
# Export to JSON for analysis
72
json_data = lief.to_json(binary)
73
```
74

75
## Architecture
76

77
LIEF provides a unified abstraction layer across different executable formats:
78

79
- **Common Base Classes**: `Binary`, `Header`, `Section`, `Symbol` provide consistent interfaces
80
- **Format-Specific Classes**: ELF, PE, and Mach-O modules extend base classes with format-specific features
81
- **Extended Features**: Assembly engine, debug information parsers, and mobile format support
82
- **Cross-Platform**: Works on Linux, Windows, macOS, iOS, and Android
83

84
The library design enables both high-level analysis through common interfaces and deep format-specific manipulation through specialized modules.
85

86
## Capabilities
87

88
### Core Binary Operations
89

90
Foundation functionality for parsing, analyzing, and modifying executable files across all supported formats with unified interfaces.
91

92
```python { .api }
93
def parse(file: Union[str, bytes, io.IOBase, os.PathLike]) -> Optional[Binary]
94
def is_elf(file: Union[str, Sequence[int]]) -> bool  
95
def is_pe(file: Union[str, Sequence[int]]) -> bool
96
def is_macho(file: Union[str, Sequence[int]]) -> bool
97
def hash(obj: Union[Object, Sequence[int], bytes, str]) -> int
98
def to_json(obj: Object) -> str
99
def demangle(mangled: str) -> Optional[str]
100
def current_platform() -> PLATFORMS
101

102
# Binary Construction and Modification
103
class ELF:
104
    class Builder:
105
        def build(self) -> Optional[bytes]
106
        def write(self, output: str) -> None
107
        
108
class PE:
109
    class Builder:
110
        def build(self) -> Optional[bytes]
111
        def write(self, output: str) -> None
112
        
113
class MachO:
114
    class Builder:
115
        def build(self) -> Optional[bytes]
116
        def write(self, output: str) -> None
117
```
118

119
[Core Operations](./core-operations.md)
120

121
### ELF Format Support
122

123
Comprehensive support for ELF (Executable and Linkable Format) files including executables, shared libraries, object files, and core dumps with Linux-specific features.
124

125
```python { .api }
126
def parse(file: Union[str, bytes, io.IOBase], config: ParserConfig = None) -> Optional[ELF.Binary]
127

128
class Binary(lief.Binary):
129
    def add_section(self, section: Section) -> Section
130
    def remove_section(self, name: str, clear: bool = False) -> None
131
    def add_library(self, library: str) -> DynamicEntryLibrary
132
    def remove_library(self, library: str) -> None
133
```
134

135
[ELF Format](./elf-format.md)
136

137
### PE Format Support
138

139
Complete support for PE (Portable Executable) format used by Windows executables, DLLs, and system files with Windows-specific features like resources and code signing.
140

141
```python { .api }
142
def parse(file: Union[str, bytes, io.IOBase], config: ParserConfig = None) -> Optional[PE.Binary]
143
def get_type(file: Union[str, Sequence[int]]) -> Union[PE_TYPE, lief_errors]
144
def get_imphash(binary: Binary, mode: IMPHASH_MODE = IMPHASH_MODE.DEFAULT) -> str
145

146
class Binary(lief.Binary):
147
    def add_section(self, section: Section) -> Section
148
    def remove_section(self, name: str, clear: bool = False) -> None
149
    def add_library(self, library: str) -> Import
150
```
151

152
[PE Format](./pe-format.md)
153

154
### Mach-O Format Support
155

156
Native support for Mach-O format used by macOS and iOS executables, frameworks, and universal binaries with Apple platform-specific features.
157

158
```python { .api }
159
def parse(file: Union[str, bytes, io.IOBase], config: ParserConfig = None) -> Optional[FatBinary]
160
def parse_from_memory(address: int, config: ParserConfig = None) -> Optional[FatBinary]
161
def is_fat(file: str) -> bool
162
def is_64(file: str) -> bool
163

164
class FatBinary:
165
    def take(self, arch: Header.CPU_TYPE) -> Optional[Binary]
166
    def add(self, binary: Binary) -> None
167
```
168

169
[Mach-O Format](./macho-format.md)
170

171
### Android Format Support
172

173
Specialized support for Android application formats including DEX bytecode, ART runtime files, OAT optimized executables, and VDEX verification data.
174

175
```python { .api }
176
def is_dex(file: Union[str, Sequence[int]]) -> bool
177
def is_art(file: Union[str, Sequence[int]]) -> bool  
178
def is_oat(file: Union[str, Sequence[int], ELF.Binary]) -> bool
179
def is_vdex(file: Union[str, Sequence[int]]) -> bool
180

181
def code_name(version: ANDROID_VERSIONS) -> str
182
def version_string(version: ANDROID_VERSIONS) -> str
183
```
184

185
[Android Formats](./android-formats.md)
186

187
### Assembly and Disassembly
188

189
Integrated disassembly and assembly engine supporting multiple architectures for code analysis and binary modification.
190

191
```python { .api }
192
class Instruction:
193
    address: int
194
    size: int  
195
    mnemonic: str
196
    raw: bytes
197
    def to_string(self, with_address: bool = True) -> str
198

199
def disassemble(self, address: int, size: int = None) -> Iterator[Optional[Instruction]]
200
def disassemble_from_bytes(self, buffer: bytes, address: int = 0) -> Iterator[Optional[Instruction]]
201
def assemble(self, address: int, assembly: str) -> bytes
202
```
203

204
[Assembly Engine](./assembly-engine.md)
205

206
### Debug Information
207

208
Advanced debug information parsing for DWARF and PDB formats enabling source-level analysis and debugging support.
209

210
```python { .api }
211
class DebugInfo:
212
    format: FORMAT  # DWARF or PDB
213
    
214
class DWARF:
215
    def find_function(self, name: str) -> Optional[Function]
216
    def find_variable(self, name: str) -> Optional[Variable]
217

218
class PDB:
219
    def functions(self) -> Iterator[Function]
220
    def public_symbols(self) -> Iterator[PublicSymbol]
221
```
222

223
[Debug Information](./debug-info.md)
224

225
### Extended Features
226

227
Advanced platform-specific features including Objective-C metadata analysis and macOS/iOS shared cache support for comprehensive Apple ecosystem analysis.
228

229
```python { .api }
230
# Objective-C Metadata
231
class ObjC:
232
    class Metadata:
233
        classes: Iterator[Class]
234
        protocols: Iterator[Protocol]
235
        
236
    class Class:
237
        name: str
238
        super_class: Optional[Class]
239
        methods: Iterator[Method]
240
        
241
# Dyld Shared Cache
242
class DyldSharedCache:
243
    def dylibs(self) -> Iterator[Dylib]
244
    def mapping_info(self) -> Iterator[MappingInfo]
245
    def find_lib_from_name(self, name: str) -> Optional[Dylib]
246
```
247

248
[Extended Features](./extended-features.md)
249

250
## Types
251

252
```python { .api }
253
class Binary:
254
    format: FORMATS
255
    header: Header
256
    sections: Iterator[Section]
257
    symbols: Iterator[Symbol] 
258
    relocations: Iterator[Relocation]
259
    entrypoint: int
260
    libraries: List[Union[str, bytes]]
261
    exported_functions: List[Function]
262
    imported_functions: List[Function]
263
    is_pie: bool
264
    has_nx: bool
265
    imagebase: int
266
    original_size: int
267
    debug_info: DebugInfo
268

269
class Header:
270
    architecture: ARCHITECTURES
271
    modes: MODES
272
    entrypoint: int
273
    object_type: OBJECT_TYPES
274
    endianness: ENDIANNESS
275
    is_32: bool
276
    is_64: bool
277

278
class Section:
279
    name: Union[str, bytes]
280
    fullname: bytes
281
    size: int
282
    offset: int 
283
    virtual_address: int
284
    content: memoryview
285
    entropy: float
286

287
class Symbol:
288
    name: Union[str, bytes]
289
    value: int
290
    size: int
291

292
class Function(Symbol):
293
    address: int
294
    flags: FLAGS
295

296
class FORMATS(enum.Enum): 
297
    UNKNOWN = 0
298
    ELF = 1
299
    PE = 2
300
    MACHO = 3
301
    OAT = 4
302

303
class PLATFORMS(enum.Enum):
304
    UNKNOWN = 0
305
    LINUX = 1  
306
    ANDROID = 2
307
    WINDOWS = 3
308
    IOS = 4
309
    OSX = 5
310

311
class lief_errors(enum.Enum):
312
    read_error = 1
313
    not_found = 2
314
    not_implemented = 3
315
    not_supported = 4
316
    corrupted = 5
317
    conversion_error = 6
318
    read_out_of_bound = 7
319
    file_error = 9
320
    file_format_error = 10
321
    parsing_error = 11
322
    build_error = 12
323
    data_too_large = 13
324
    require_extended_version = 14
325
```