tessl/pypi-lief

Library to instrument executable formats including ELF, PE, Mach-O, and Android formats

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

LIEF

Name: tessl/pypi-lief
Author: tessl

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.

Package Information

Package Name: lief
Package Type: PyPI
Language: Python (with C++ backend)
Installation: pip install lief

Core Imports

import lief
from typing import Union, Optional, Iterator, List, Sequence
import io
import os

For format-specific operations:

import lief.ELF
import lief.PE  
import lief.MachO
import lief.Android
# Android-specific formats
import lief.DEX
import lief.ART
import lief.OAT
import lief.VDEX

For extended features:

import lief.assembly
import lief.dwarf
import lief.pdb
import lief.objc
import lief.dsc

Basic Usage

import lief

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

if binary is None:
    print("Unable to parse binary")
    exit(1)

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

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

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

# Export to JSON for analysis
json_data = lief.to_json(binary)

Architecture

LIEF provides a unified abstraction layer across different executable formats:

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

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

Capabilities

Core Binary Operations

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

def parse(file: Union[str, bytes, io.IOBase, os.PathLike]) -> Optional[Binary]
def is_elf(file: Union[str, Sequence[int]]) -> bool  
def is_pe(file: Union[str, Sequence[int]]) -> bool
def is_macho(file: Union[str, Sequence[int]]) -> bool
def hash(obj: Union[Object, Sequence[int], bytes, str]) -> int
def to_json(obj: Object) -> str
def demangle(mangled: str) -> Optional[str]
def current_platform() -> PLATFORMS

# Binary Construction and Modification
class ELF:
    class Builder:
        def build(self) -> Optional[bytes]
        def write(self, output: str) -> None
        
class PE:
    class Builder:
        def build(self) -> Optional[bytes]
        def write(self, output: str) -> None
        
class MachO:
    class Builder:
        def build(self) -> Optional[bytes]
        def write(self, output: str) -> None

Core Operations

ELF Format Support

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

def parse(file: Union[str, bytes, io.IOBase], config: ParserConfig = None) -> Optional[ELF.Binary]

class Binary(lief.Binary):
    def add_section(self, section: Section) -> Section
    def remove_section(self, name: str, clear: bool = False) -> None
    def add_library(self, library: str) -> DynamicEntryLibrary
    def remove_library(self, library: str) -> None

ELF Format

PE Format Support

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

def parse(file: Union[str, bytes, io.IOBase], config: ParserConfig = None) -> Optional[PE.Binary]
def get_type(file: Union[str, Sequence[int]]) -> Union[PE_TYPE, lief_errors]
def get_imphash(binary: Binary, mode: IMPHASH_MODE = IMPHASH_MODE.DEFAULT) -> str

class Binary(lief.Binary):
    def add_section(self, section: Section) -> Section
    def remove_section(self, name: str, clear: bool = False) -> None
    def add_library(self, library: str) -> Import

PE Format

Mach-O Format Support

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

def parse(file: Union[str, bytes, io.IOBase], config: ParserConfig = None) -> Optional[FatBinary]
def parse_from_memory(address: int, config: ParserConfig = None) -> Optional[FatBinary]
def is_fat(file: str) -> bool
def is_64(file: str) -> bool

class FatBinary:
    def take(self, arch: Header.CPU_TYPE) -> Optional[Binary]
    def add(self, binary: Binary) -> None

Mach-O Format

Android Format Support

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

def is_dex(file: Union[str, Sequence[int]]) -> bool
def is_art(file: Union[str, Sequence[int]]) -> bool  
def is_oat(file: Union[str, Sequence[int], ELF.Binary]) -> bool
def is_vdex(file: Union[str, Sequence[int]]) -> bool

def code_name(version: ANDROID_VERSIONS) -> str
def version_string(version: ANDROID_VERSIONS) -> str

Android Formats

Assembly and Disassembly

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

class Instruction:
    address: int
    size: int  
    mnemonic: str
    raw: bytes
    def to_string(self, with_address: bool = True) -> str

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

Assembly Engine

Debug Information

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

class DebugInfo:
    format: FORMAT  # DWARF or PDB
    
class DWARF:
    def find_function(self, name: str) -> Optional[Function]
    def find_variable(self, name: str) -> Optional[Variable]

class PDB:
    def functions(self) -> Iterator[Function]
    def public_symbols(self) -> Iterator[PublicSymbol]

Debug Information

Extended Features

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

# Objective-C Metadata
class ObjC:
    class Metadata:
        classes: Iterator[Class]
        protocols: Iterator[Protocol]
        
    class Class:
        name: str
        super_class: Optional[Class]
        methods: Iterator[Method]
        
# Dyld Shared Cache
class DyldSharedCache:
    def dylibs(self) -> Iterator[Dylib]
    def mapping_info(self) -> Iterator[MappingInfo]
    def find_lib_from_name(self, name: str) -> Optional[Dylib]

Extended Features

Types

class Binary:
    format: FORMATS
    header: Header
    sections: Iterator[Section]
    symbols: Iterator[Symbol] 
    relocations: Iterator[Relocation]
    entrypoint: int
    libraries: List[Union[str, bytes]]
    exported_functions: List[Function]
    imported_functions: List[Function]
    is_pie: bool
    has_nx: bool
    imagebase: int
    original_size: int
    debug_info: DebugInfo

class Header:
    architecture: ARCHITECTURES
    modes: MODES
    entrypoint: int
    object_type: OBJECT_TYPES
    endianness: ENDIANNESS
    is_32: bool
    is_64: bool

class Section:
    name: Union[str, bytes]
    fullname: bytes
    size: int
    offset: int 
    virtual_address: int
    content: memoryview
    entropy: float

class Symbol:
    name: Union[str, bytes]
    value: int
    size: int

class Function(Symbol):
    address: int
    flags: FLAGS

class FORMATS(enum.Enum): 
    UNKNOWN = 0
    ELF = 1
    PE = 2
    MACHO = 3
    OAT = 4

class PLATFORMS(enum.Enum):
    UNKNOWN = 0
    LINUX = 1  
    ANDROID = 2
    WINDOWS = 3
    IOS = 4
    OSX = 5

class lief_errors(enum.Enum):
    read_error = 1
    not_found = 2
    not_implemented = 3
    not_supported = 4
    corrupted = 5
    conversion_error = 6
    read_out_of_bound = 7
    file_error = 9
    file_format_error = 10
    parsing_error = 11
    build_error = 12
    data_too_large = 13
    require_extended_version = 14