LIEF - Library to Instrument Executable Formats

Warnings

• breaking LIEF v0.17.0 introduced a significant refactoring of the PE parser and builder API to align with ELF and Mach-O functionalities. Codebases processing PE binaries may require updates.
  Fix: Review the 'PE Changelog for LIEF 0.17.0' documentation for specific API changes and migration guidance. Functions returning references that previously threw exceptions now return pointers (or Python `None`) on failure.
• gotcha When parsing PE files (especially from v0.17.0 onwards), certain in-depth metadata (e.g., ARM64X binaries, exceptions, exports, imports, relocations, resources, signatures) might not be parsed by default. These options must be explicitly enabled.
  Fix: Use `lief.PE.ParserConfig` to enable desired parsing options. For example, `config = lief.PE.ParserConfig(); config.parse_exports = True; binary = lief.PE.parse('path/to/pe.exe', config)`. Review `lief.PE.ParserConfig` for available flags.
• breaking The `create_pe_from_scratch` feature (for building PE files from zero) was deprecated and removed in LIEF 0.17.0 due to significant bugs that often led to corrupted binaries.
  Fix: Avoid using the `create_pe_from_scratch` functionality. Focus on modifying existing binaries, which has seen improvements in the builder engine.
• gotcha Prior to version 0.17.0, modifying PE files using the Python API was highly bugged and often resulted in unexpected file size increases or corrupted binaries, especially when modifying sections like `.rsrc`.
  Fix: Upgrade to LIEF 0.17.0 or newer, as the builder engine for PE files has been refactored to address these limitations and provide a more conservative approach to modifications.
• deprecated LIEF v0.14.0 moved from Pybind11 to nanobind for its Python bindings. While this improved performance and compilation, internal changes for `setuptools` (replaced by `scikit-build-core`) could affect custom build processes.
  Fix: Projects that compile LIEF from source or have custom build setups should review their build configurations, especially regarding `setuptools` and `scikit-build-core` as mentioned in the v0.14.0 changelog.

Install

• pip install lief Install stable version from PyPI

Imports

• lief

  import lief

  The primary import for accessing all LIEF functionalities.
• lief.ELF

  import lief
  elf_binary = lief.ELF.parse('/bin/ls')

  Access specific format parsers directly for clarity or C++-like behavior.
• lief.PE

  import lief
  pe_binary = lief.PE.parse('C:\\Windows\\System32\\notepad.exe')

  Access specific format parsers directly for clarity or C++-like behavior.

Quickstart

This quickstart demonstrates how to use `lief.parse()` to automatically detect and parse an executable file (ELF on Linux/macOS, PE on Windows). It then prints basic information about the binary, showcasing format-specific attributes like ELF machine type or number of PE imported libraries. Replace the default paths with your target binaries.

import lief
import sys
import os

def analyze_binary(filepath):
    if not os.path.exists(filepath):
        print(f"Error: File not found at {filepath}")
        return

    binary = lief.parse(filepath)

    if binary is None:
        print(f"Could not parse {filepath} as an executable.")
        return

    print(f"\nAnalyzing: {filepath}")
    print(f"  Format: {binary.format}")
    print(f"  Entrypoint: {hex(binary.entrypoint)}")
    print(f"  Number of sections: {len(binary.sections)}")

    # Example: Accessing ELF-specific features
    if binary.format == lief.Binary.FORMATS.ELF:
        elf_binary = binary.as_elf()
        if elf_binary and elf_binary.header:
            print(f"  ELF Machine Type: {elf_binary.header.machine_type}")
            if elf_binary.dynamic_entries:
                print(f"  Number of dynamic entries: {len(elf_binary.dynamic_entries)}")

    # Example: Accessing PE-specific features
    elif binary.format == lief.Binary.FORMATS.PE:
        pe_binary = binary.as_pe()
        if pe_binary and pe_binary.header:
            print(f"  PE Machine Type: {pe_binary.header.machine_type}")
            if pe_binary.imports:
                print(f"  Number of imported libraries: {len(pe_binary.imports)}")

# Try to analyze common executables based on OS
if sys.platform.startswith('linux'):
    analyze_binary('/bin/ls')
elif sys.platform == 'win32':
    analyze_binary('C:\\Windows\\System32\\notepad.exe')
elif sys.platform == 'darwin':
    analyze_binary('/bin/ls') # macOS also uses ELF/MachO, /bin/ls is a good example
else:
    print("Unsupported OS for quickstart example.")