0
# Core Operations
1

2
Foundation functionality for parsing, analyzing, and modifying executable files across all supported formats. These operations provide unified interfaces that work consistently regardless of the underlying binary format.
3

4
## Capabilities
5

6
### Binary Parsing
7

8
Parse executable files from various sources with automatic format detection and unified interface access.
9

10
```python { .api }
11
# Core imports required
12
import lief
13
from typing import Union, Optional, Sequence, Iterator, List
14
import io
15
import os
16

17
def parse(file: Union[str, bytes, io.IOBase, os.PathLike]) -> Optional[Binary]:
18
    """
19
    Parse binary files with automatic format detection.
20
    
21
    Args:
22
        file: File path, raw bytes, or file-like object
23
        
24
    Returns:
25
        Binary object or None if parsing fails
26
    """
27

28
def parse(filepath: str) -> Optional[Binary]: ...
29
def parse(raw: bytes) -> Optional[Binary]: ...  
30
def parse(obj: Union[io.IOBase, os.PathLike]) -> Optional[Binary]: ...
31
```
32

33
Usage example:
34
```python
35
import lief
36

37
# Parse from file path
38
binary = lief.parse("/bin/ls")
39

40
# Parse from bytes
41
with open("/bin/ls", "rb") as f:
42
    binary = lief.parse(f.read())
43

44
# Parse from file object  
45
with open("/bin/ls", "rb") as f:
46
    binary = lief.parse(f)
47
```
48

49
### Format Detection
50

51
Identify binary formats before parsing for conditional processing and validation.
52

53
```python { .api }
54
def is_elf(file: Union[str, Sequence[int]]) -> bool:
55
    """Check if file is ELF format."""
56

57
def is_pe(file: Union[str, Sequence[int]]) -> bool:
58
    """Check if file is PE format."""
59
    
60
def is_macho(file: Union[str, Sequence[int]]) -> bool:
61
    """Check if file is Mach-O format."""
62
    
63
def is_oat(file: Union[ELF.Binary, str, Sequence[int]]) -> bool:
64
    """Check if file is OAT format."""
65
    
66
def is_dex(file: Union[str, Sequence[int]]) -> bool:
67
    """Check if file is DEX format."""
68
    
69
def is_vdex(file: Union[str, Sequence[int]]) -> bool:
70
    """Check if file is VDEX format."""
71
    
72
def is_art(file: Union[str, Sequence[int]]) -> bool:
73
    """Check if file is ART format."""
74
```
75

76
Usage example:
77
```python
78
import lief
79

80
file_path = "/bin/bash"
81

82
if lief.is_elf(file_path):
83
    binary = lief.ELF.parse(file_path)
84
elif lief.is_pe(file_path):
85
    binary = lief.PE.parse(file_path)  
86
elif lief.is_macho(file_path):
87
    binary = lief.MachO.parse(file_path)
88
```
89

90
### Binary Analysis
91

92
Access common properties and perform analysis operations across all binary formats.
93

94
```python { .api }
95
class Binary:
96
    format: FORMATS
97
    header: Header
98
    sections: Iterator[Section]
99
    symbols: Iterator[Symbol]
100
    relocations: Iterator[Relocation]
101
    entrypoint: int
102
    libraries: List[Union[str, bytes]]
103
    exported_functions: List[Function]
104
    imported_functions: List[Function]
105
    is_pie: bool
106
    has_nx: bool
107
    imagebase: int
108
    original_size: int
109
    debug_info: Optional[DebugInfo]
110
    ctor_functions: List[Function]
111
    
112
    def has_symbol(self, symbol_name: str) -> bool
113
    def get_symbol(self, symbol_name: str) -> Symbol
114
    def get_function_address(self, function_name: str) -> Union[int, lief_errors]
115
    def remove_section(self, name: str, clear: bool = False) -> None
116
    def offset_to_virtual_address(self, offset: int, slide: int = 0) -> Union[int, lief_errors]
117
    def xref(self, virtual_address: int) -> List[int]
118
```
119

120
Usage example:
121
```python
122
binary = lief.parse("/bin/ls")
123

124
print(f"Format: {binary.format}")
125
print(f"Architecture: {binary.header.architecture}")
126
print(f"Entry point: 0x{binary.entrypoint:x}")
127
print(f"PIE enabled: {binary.is_pie}")
128
print(f"NX protection: {binary.has_nx}")
129

130
# Symbol analysis
131
if binary.has_symbol("main"):
132
    main_addr = binary.get_function_address("main")
133
    print(f"main() at: 0x{main_addr:x}")
134

135
# Section analysis
136
for section in binary.sections:
137
    print(f"{section.name}: {section.size} bytes at 0x{section.virtual_address:x}")
138
```
139

140
### Binary Modification
141

142
Modify binary content through unified interfaces that work across formats.
143

144
```python { .api }
145
class Binary:
146
    def patch_address(self, address: int, patch_value: Union[Sequence[int], int], 
147
                     size: int = 8, va_type: VA_TYPES = VA_TYPES.AUTO) -> None:
148
        """Patch binary at specified address."""
149
        
150
    def get_content_from_virtual_address(self, virtual_address: int, size: int, 
151
                                       va_type: VA_TYPES = VA_TYPES.AUTO) -> memoryview:
152
        """Read content from virtual address."""
153
        
154
    def get_int_from_virtual_address(self, address: int, integer_size: int, 
155
                                   type: VA_TYPES = VA_TYPES.AUTO) -> Optional[int]:
156
        """Read integer from virtual address."""
157
```
158

159
Usage example:
160
```python
161
binary = lief.parse("/path/to/binary")
162

163
# Read data from virtual address
164
data = binary.get_content_from_virtual_address(0x1000, 16)
165
print(f"Data: {data.hex()}")
166

167
# Patch binary
168
binary.patch_address(0x1000, [0x90, 0x90, 0x90, 0x90])  # NOP sled
169

170
# Read integer from address
171
value = binary.get_int_from_virtual_address(0x2000, 4)
172
print(f"Value: {value}")
173
```
174

175
### Utility Functions
176

177
Helper functions for common operations and data manipulation.
178

179
```python { .api }
180
def hash(obj: Union[Object, Sequence[int], bytes, str]) -> int:
181
    """Compute hash of LIEF objects or data."""
182
    
183
def to_json(obj: Object) -> str:
184
    """Convert LIEF objects to JSON representation."""
185
    
186
def demangle(mangled: str) -> Optional[str]:
187
    """Demangle C++ symbol names."""
188
    
189
def current_platform() -> PLATFORMS:
190
    """Get current platform (Linux, Windows, macOS, etc.)."""
191
    
192
def disable_leak_warning() -> None:
193
    """Disable memory leak warnings."""
194
```
195

196
Usage example:
197
```python
198
import lief
199

200
binary = lief.parse("/bin/ls")
201

202
# Generate hash
203
binary_hash = lief.hash(binary)
204
print(f"Binary hash: {binary_hash}")
205

206
# Export to JSON
207
json_data = lief.to_json(binary)
208
with open("analysis.json", "w") as f:
209
    f.write(json_data)
210

211
# Demangle symbols
212
for symbol in binary.symbols:
213
    if symbol.name.startswith("_Z"):
214
        demangled = lief.demangle(symbol.name)
215
        print(f"{symbol.name} -> {demangled}")
216

217
# Platform detection  
218
platform = lief.current_platform()
219
print(f"Running on: {platform}")
220
```
221

222
### Assembly Integration
223

224
Disassemble and assemble code directly from binary objects for analysis and modification.
225

226
```python { .api }
227
class Binary:
228
    def disassemble(self, address: int, size: int = None) -> Iterator[Optional[assembly.Instruction]]:
229
        """Disassemble instructions at address."""
230
        
231
    def disassemble(self, function_name: str) -> Iterator[Optional[assembly.Instruction]]:
232
        """Disassemble entire function by name."""
233
        
234
    def disassemble_from_bytes(self, buffer: bytes, address: int = 0) -> Iterator[Optional[assembly.Instruction]]:
235
        """Disassemble raw bytes."""
236
        
237
    def assemble(self, address: int, assembly: str) -> bytes:
238
        """Assemble instructions and return machine code."""
239
```
240

241
Usage example:
242
```python
243
binary = lief.parse("/bin/ls")
244

245
# Disassemble function
246
for instruction in binary.disassemble("main"):
247
    if instruction:
248
        print(f"0x{instruction.address:x}: {instruction.mnemonic}")
249

250
# Disassemble at specific address
251
for instruction in binary.disassemble(binary.entrypoint, 32):
252
    if instruction:
253
        print(instruction.to_string())
254

255
# Assemble instructions
256
machine_code = binary.assemble(0x1000, "mov rax, 42\nret")
257
print(f"Machine code: {machine_code.hex()}")
258
```
259

260
## Types
261

262
```python { .api }
263
class range_t:
264
    low: int
265
    high: int
266
    size: int
267

268
class debug_location_t:
269
    line: int
270
    file: str
271

272
class ok_t:
273
    def __bool__(self) -> bool
274

275
class ok_error_t:  
276
    is_error: bool
277
    is_value: bool
278
    error: lief_errors
279
    value: ok_t
280
    def __bool__(self) -> bool
281

282
enum PLATFORMS:
283
    UNKNOWN = 0
284
    LINUX = 1
285
    ANDROID = 2  
286
    WINDOWS = 3
287
    IOS = 4
288
    OSX = 5
289

290
enum VA_TYPES:
291
    AUTO = 0
292
    RVA = 1
293
    VA = 2
294

295
enum lief_errors:
296
    read_error = 1
297
    not_found = 2
298
    not_implemented = 3
299
    not_supported = 4
300
    corrupted = 5
301
    conversion_error = 6
302
    read_out_of_bound = 7
303
    asn1_bad_tag = 8
304
    file_error = 9
305
    file_format_error = 10
306
    parsing_error = 11
307
    build_error = 12
308
    data_too_large = 13
309
    require_extended_version = 14
310
```