Python¶

Parser¶

Parse the COFF binary specified in the first parameter and return a lief.COFF.Binary object

The second argument is an optional configuration that can be used to define which part(s) of the COFF should be parsed or skipped.

class lief.COFF.ParserConfig(self)¶

Bases: object

all = <lief._lief.COFF.ParserConfig object>¶

default_conf = <lief._lief.COFF.ParserConfig object>¶

Binary¶

class lief.COFF.Binary¶

Bases: object

Class that represents a COFF Binary

disassemble(self, function: lief._lief.COFF.Symbol) → Iterator[lief._lief.assembly.Instruction | None]¶

disassemble(self, function_name: str) → Iterator[lief._lief.assembly.Instruction | None]

Overloaded function.

disassemble(self, function: lief._lief.COFF.Symbol) -> Iterator[Optional[lief._lief.assembly.Instruction]]
Disassemble code for the given symbol
func = binary.find_demangled_function("int __cdecl my_function(int, int)"); insts = binary.disassemble("main"); for inst in insts: print(inst)
See also
lief.assembly.Instruction
disassemble(self, function_name: str) -> Iterator[Optional[lief._lief.assembly.Instruction]]
Disassemble code for the given symbol name
insts = binary.disassemble("main"); for inst in insts: print(inst)
See also
lief.assembly.Instruction

disassemble_from_bytes(self, buffer: bytes, address: int = 0) → Iterator[lief._lief.assembly.Instruction | None]¶

Disassemble code from the provided bytes

raw = bytes(binary.get_section(".text").content)
insts = binary.disassemble_from_bytes(raw);
for inst in insts:
    print(inst)

Header¶

class lief.COFF.Header¶

Bases: object

Class that represents the COFF header. It is subclassed by RegularHeader and BigObjHeader for normal vs /bigobj files

class KIND(*values)¶

Bases: Enum

BIGOBJ = 2¶

REGULAR = 1¶

UNKNOWN = 0¶

copy(self) → lief._lief.COFF.Header | None¶: Duplicate the current instance of this object

property kind → lief.COFF.Header.KIND¶: The type of this header: whether it is regular or using the /bigobj format

property machine → lief.PE.Header.MACHINE_TYPES¶: The machine type targeted by this COFF

property nb_sections → int¶: The number of sections

property nb_symbols → int¶: Number of symbols (including auxiliary symbols)

property pointerto_symbol_table → int¶: Offset of the symbols table

property timedatestamp → int¶: Timestamp when the COFF has been generated

RegularHeader¶

class lief.COFF.RegularHeader¶

Bases: Header

This class represents the COFF header for non-bigobj

property characteristics → int¶: Characteristics

property sizeof_optionalheader → int¶: The size of the optional header that follows this header (should be 0)

BigObjHeader¶

class lief.COFF.BigObjHeader¶

Bases: Header

This class represents the header for a COFF object compiled with /bigobj support (i.e. the number of sections can exceed 65536).

The raw definition of the bigobj header is located in winnt.h and named ANON_OBJECT_HEADER_BIGOBJ

property flags → int¶: 1 means that it contains metadata

property metadata_offset → int¶: Offset of CLR metadata

property metadata_size → int¶: Size of CLR metadata

property sizeof_data → int¶: Size of data that follows the header

property uuid → memoryview¶: Originally named ClassID, this uuid should match: {D1BAA1C7-BAEE-4ba9-AF20-FAF66AA4DCB8}.

property version → int¶: The version of this header which must be >= 2

Section¶

class lief.COFF.Section¶

Bases: Section

This class represents a COFF section

class ComdatInfo¶

Bases: object

This class wraps comdat information which is composed of the symbol associated with the comdat section and its selection flag

property kind → lief.COFF.AuxiliarySectionDefinition.COMDAT_SELECTION¶

property symbol → lief.COFF.Symbol¶

property characteristics → int¶: The characteristics that describe the purpose of the section

property characteristics_lists → list[lief.PE.Section.CHARACTERISTICS]¶: characteristics as a list

property coff_string → lief.COFF.String | None¶

Return the COFF string associated with the section’s name (or None)

This coff string is usually present for long section names whose length does not fit in the 8 bytes allocated by the COFF format.

property comdat_info → lief.COFF.Section.ComdatInfo | None¶: Return comdat information (only if the section has the lief.PE.Section.CHARACTERISTICS.LNK_COMDAT characteristic)

has_characteristic(self, characteristic: lief._lief.PE.Section.CHARACTERISTICS) → bool¶: True if the section has the given characteristic

property has_extended_relocations → bool¶: Whether there is a large number of relocations whose number need to be stored in the virtual address attribute

property is_discardable → bool¶

True if the section can be discarded as needed.

This is typically the case for debug-related sections.

property numberof_line_numbers → int¶

The number of line-number entries for the section. This value should be zero for an image because COFF debugging information is deprecated.

See: pointerto_line_numbers

property numberof_relocations → int¶: Number of relocations.

Warning
If the number of relocations is greater than 0xFFFF (maximum value for 16-bits integer), then the number of relocations is stored in the virtual address attribute.

property pointerto_line_numbers → int¶: The file pointer to the beginning of line-number entries for the section. This is set to zero if there are no COFF line numbers. This value should be zero for an image because COFF debugging information is deprecated and modern debug information relies on the PDB files.

property pointerto_raw_data → int¶: Offset to the section’s content

property pointerto_relocation → int¶: Offset to the relocation table

property relocations → lief.COFF.Section.it_relocations¶: Iterator over the relocations performed in this section

property sizeof_raw_data → int¶: Return the size of the data in the section.

property symbols → lief.COFF.Section.it_symbols¶: Iterator over the symbols associated with this section

property virtual_size → int¶: Virtual size of the section (should be 0)

Relocation¶

class lief.COFF.Relocation¶

Bases: Relocation

class TYPE(*values)¶

Bases: Enum

AMD64_ABSOLUTE = 262144¶

AMD64_ADDR32 = 262146¶

AMD64_ADDR32NB = 262147¶

AMD64_ADDR64 = 262145¶

AMD64_PAIR = 262159¶

AMD64_REL32 = 262148¶

AMD64_REL32_1 = 262149¶

AMD64_REL32_2 = 262150¶

AMD64_REL32_3 = 262151¶

AMD64_REL32_4 = 262152¶

AMD64_REL32_5 = 262153¶

AMD64_SECREL = 262155¶

AMD64_SECREL7 = 262156¶

AMD64_SECTION = 262154¶

AMD64_SREL32 = 262158¶

AMD64_SSPAN32 = 262160¶

AMD64_TOKEN = 262157¶

ARM64_ABSOLUTE = 1048576¶

ARM64_ADDR32 = 1048577¶

ARM64_ADDR32NB = 1048578¶

ARM64_ADDR64 = 1048590¶

ARM64_BRANCH14 = 1048592¶

ARM64_BRANCH19 = 1048591¶

ARM64_BRANCH26 = 1048579¶

ARM64_PAGEBASE_REL21 = 1048580¶

ARM64_PAGEOFFSET_12A = 1048582¶

ARM64_PAGEOFFSET_12L = 1048583¶

ARM64_REL21 = 1048581¶

ARM64_REL32 = 1048593¶

ARM64_SECREL = 1048584¶

ARM64_SECREL_HIGH12A = 1048586¶

ARM64_SECREL_LOW12A = 1048585¶

ARM64_SECREL_LOW12L = 1048587¶

ARM64_SECTION = 1048589¶

ARM64_TOKEN = 1048588¶

ARM_ABSOLUTE = 524288¶

ARM_ADDR32 = 524289¶

ARM_ADDR32NB = 524290¶

ARM_BLX11 = 524297¶

ARM_BLX23T = 524309¶

ARM_BLX24 = 524296¶

ARM_BRANCH11 = 524292¶

ARM_BRANCH20T = 524306¶

ARM_BRANCH24 = 524291¶

ARM_BRANCH24T = 524308¶

ARM_MOV32A = 524304¶

ARM_MOV32T = 524305¶

ARM_PAIR = 524310¶

ARM_REL32 = 524298¶

ARM_SECREL = 524303¶

ARM_SECTION = 524302¶

ARM_TOKEN = 524293¶

I386_ABSOLUTE = 131072¶

I386_DIR16 = 131073¶

I386_DIR32 = 131078¶

I386_DIR32NB = 131079¶

I386_REL16 = 131074¶

I386_REL32 = 131092¶

I386_SECREL = 131083¶

I386_SECREL7 = 131085¶

I386_SECTION = 131082¶

I386_SEG12 = 131081¶

I386_TOKEN = 131084¶

MIPS_ABSOLUTE = 2097152¶

MIPS_GPREL = 2097158¶

MIPS_JMPADDR = 2097155¶

MIPS_JMPADDR16 = 2097168¶

MIPS_LITERAL = 2097159¶

MIPS_PAIR = 2097189¶

MIPS_REFHALF = 2097153¶

MIPS_REFHI = 2097156¶

MIPS_REFLO = 2097157¶

MIPS_REFWORD = 2097154¶

MIPS_REFWORDNB = 2097186¶

MIPS_SECREL = 2097163¶

MIPS_SECRELHI = 2097165¶

MIPS_SECRELLO = 2097164¶

MIPS_SECTION = 2097162¶

UNKNOWN = 4294967295¶

from_value(arg: int) → lief.COFF.Relocation.TYPE = <nanobind.nb_func object>¶

property section → lief.COFF.Section | None¶: Section in which the relocation takes place

property symbol → lief.COFF.Symbol | None¶: Symbol associated with the relocation (if any)

property symbol_idx → int¶: Symbol index associated with this relocation

property type → lief.COFF.Relocation.TYPE¶: Type of the relocation

String¶

class lief.COFF.String¶

Bases: object

This class represents a string located in the COFF string table.

Some of these strings can be used for section’s name where its length is greater than 8 bytes. See: coff_string.

Reference: https://learn.microsoft.com/en-us/windows/win32/debug/pe-format#coff-string-table

property offset → int¶: The offset of this string the in the COFF string table. This offset includes the first 4-bytes that holds the table size

property string → str¶: The actual string

Symbol¶

class lief.COFF.Symbol¶

Bases: Symbol

Class that represents a COFF symbol.

Warning

The lief.Symbol.value should be interpreted in perspective of the storage_class

Reference: https://learn.microsoft.com/en-us/windows/win32/debug/pe-format#coff-symbol-table

class BASE_TYPE(*values)¶

Bases: Enum

BYTE = 12¶

CHAR = 2¶

DOUBLE = 7¶

DWORD = 15¶

ENUM = 10¶

FLOAT = 6¶

INT = 4¶

LONG = 5¶

MOE = 11¶

NULL = 0¶

SHORT = 3¶

STRUCT = 8¶

UINT = 14¶

UNION = 9¶

VOID = 1¶

WORD = 13¶

from_value(arg: int) → lief.COFF.Symbol.BASE_TYPE = <nanobind.nb_func object>¶

class COMPLEX_TYPE(*values)¶

Bases: Enum

ARRAY = 3¶

FUNCTION = 2¶

NULL = 0¶

POINTER = 1¶

from_value(arg: int) → lief.COFF.Symbol.COMPLEX_TYPE = <nanobind.nb_func object>¶

class STORAGE_CLASS(*values)¶

Bases: Enum

Reference: https://learn.microsoft.com/en-us/windows/win32/debug/pe-format#storage-class

ARGUMENT = 9¶

AUTOMATIC = 1¶

BIT_FIELD = 18¶

BLOCK = 100¶

CLR_TOKEN = 107¶

END_OF_FUNCTION = -1¶

END_OF_STRUCT = 102¶

ENUM_TAG = 15¶

EXTERNAL = 2¶

EXTERNAL_DEF = 5¶

FILE = 103¶

FUNCTION = 101¶

LABEL = 6¶

MEMBER_OF_ENUM = 16¶

MEMBER_OF_STRUCT = 8¶

MEMBER_OF_UNION = 11¶

NONE = 0¶

REGISTER = 4¶

REGISTER_PARAM = 17¶

SECTION = 104¶

STATIC = 3¶

STRUCT_TAG = 10¶

TYPE_DEFINITION = 13¶

UNDEFINED_LABEL = 7¶

UNDEFINED_STATIC = 14¶

UNION_TAG = 12¶

WEAK_EXTERNAL = 105¶

from_value(arg: int) → lief.COFF.Symbol.STORAGE_CLASS = <nanobind.nb_func object>¶

property auxiliary_symbols → lief.COFF.Symbol.it_auxiliary_symbols_t¶: Auxiliary symbols associated with this symbol.

property base_type → lief.COFF.Symbol.BASE_TYPE¶: The simple (base) data type

property coff_name → lief.COFF.String | None¶: COFF string used to represents the (long) symbol name

property complex_type → lief.COFF.Symbol.COMPLEX_TYPE¶: The complex type (if any)

property demangled_name → str¶: Demangled representation of the symbol or an empty string if it can’t be demangled

property is_absolute → bool¶

property is_external → bool¶

property is_file_record → bool¶

property is_function → bool¶

property is_function_line_info → bool¶

property is_undefined → bool¶

property is_weak_external → bool¶

property section → lief.COFF.Section | None¶: Section associated with this symbol (if any)

property section_idx → int¶

The signed integer that identifies the section, using a one-based index into the section table. Some values have special meaning:

0: The symbol record is not yet assigned a section. A value of zero
indicates that a reference to an external symbol is defined elsewhere. A value of non-zero is a common symbol with a size that is specified by the value.
-1: The symbol has an absolute (non-relocatable) value and is not an
address.
-2: The symbol provides general type or debugging information but does
not correspond to a section. Microsoft tools use this setting along with .file records

property storage_class → lief.COFF.Symbol.STORAGE_CLASS¶: Storage class of the symbol which indicates what kind of definition a symbol represents.

property type → int¶: The symbol type. The first byte represents the base type (see: base_type) while the upper byte represents the complex type, if any (see: complex_type).

AuxiliarySymbol¶

Inheritance diagram of lief._lief.COFF.AuxiliarySectionDefinition, lief._lief.COFF.AuxiliaryFile, lief._lief.COFF.AuxiliarybfAndefSymbol, lief._lief.COFF.AuxiliaryWeakExternal, lief._lief.COFF.AuxiliaryCLRToken, lief._lief.COFF.AuxiliarySymbol, lief._lief.COFF.AuxiliaryFunctionDefinition

class lief.COFF.AuxiliarySymbol¶

Bases: object

Class that represents an auxiliary symbol.

An auxiliary symbol has the same size as a regular lief.PE.Symbol (18 bytes) but its content depends on the parent symbol.

class TYPE(*values)¶

Bases: Enum

Type discriminator for the subclasses

BF_AND_EF = 3¶

CLR_TOKEN = 1¶

FILE = 5¶

FUNC_DEF = 2¶

SEC_DEF = 6¶

UNKNOWN = 0¶

WEAK_EXTERNAL = 4¶

from_value(arg: int) → lief.COFF.AuxiliarySymbol.TYPE = <nanobind.nb_func object>¶

copy(self) → lief._lief.COFF.AuxiliarySymbol | None¶: Duplicate the current instance of this object

property payload → memoryview¶: For unknown type only, return the raw representation of this symbol

property type → lief.COFF.AuxiliarySymbol.TYPE¶

AuxiliaryCLRToken¶

class lief.COFF.AuxiliaryCLRToken¶

Bases: AuxiliarySymbol

Auxiliary symbol associated with the CLR_TOKEN storage class

property aux_type → int¶: IMAGE_AUX_SYMBOL_TYPE which should be IMAGE_AUX_SYMBOL_TYPE_TOKEN_DEF (1)

property reserved → int¶: Reserved value (should be 0)

property rgb_reserved → memoryview¶: Reserved (padding) values. Should be 0

property symbol → lief.COFF.Symbol | None¶: Symbol referenced by symbol_idx (if resolved)

property symbol_idx → int¶: Index in the symbol table

AuxiliaryFunctionDefinition¶

class lief.COFF.AuxiliaryFunctionDefinition¶

Bases: AuxiliarySymbol

This auxiliary symbol marks the beginning of a function definition.

Reference: https://learn.microsoft.com/en-us/windows/win32/debug/pe-format#auxiliary-format-1-function-definitions

property padding → int¶: Padding value (should be 0)

property ptr_to_line_number → int¶: The file offset of the first COFF line-number entry for the function, or zero if none exists (deprecated)

property ptr_to_next_func → int¶: The symbol-table index of the record for the next function. If the function is the last in the symbol table, this field is set to zero

property tag_index → int¶: The symbol-table index of the corresponding .bf (begin function) symbol record.

property total_size → int¶

The size of the executable code for the function itself.

If the function is in its own section, the SizeOfRawData in the section header is greater or equal to this field, depending on alignment considerations

AuxiliaryWeakExternal¶

class lief.COFF.AuxiliaryWeakExternal¶

Bases: AuxiliarySymbol

“Weak externals” are a mechanism for object files that allows flexibility at link time. A module can contain an unresolved external symbol (sym1), but it can also include an auxiliary record that indicates that if sym1 is not present at link time, another external symbol (sym2) is used to resolve references instead.

If a definition of sym1 is linked, then an external reference to the symbol is resolved normally. If a definition of sym1 is not linked, then all references to the weak external for sym1 refer to sym2 instead. The external symbol, sym2, must always be linked; typically, it is defined in the module that contains the weak reference to sym1.

Reference: https://learn.microsoft.com/en-us/windows/win32/debug/pe-format#auxiliary-format-3-weak-externals

class CHARACTERISTICS(*values)¶

Bases: Enum

ANTI_DEPENDENCY = 4¶

SEARCH_ALIAS = 3¶

SEARCH_LIBRARY = 2¶

SEARCH_NOLIBRARY = 1¶

property characteristics → lief.COFF.AuxiliaryWeakExternal.CHARACTERISTICS¶

property padding → memoryview¶

property sym_idx → int¶: The symbol-table index of sym2, the symbol to be linked if sym1 is not found.

AuxiliarybfAndefSymbol¶

class lief.COFF.AuxiliarybfAndefSymbol¶: Bases: AuxiliarySymbol

AuxiliarySectionDefinition¶

class lief.COFF.AuxiliarySectionDefinition¶

Bases: AuxiliarySymbol

This auxiliary symbol exposes information about the associated section.

It duplicates some information that are provided in the section header

class COMDAT_SELECTION(*values)¶

Bases: Enum

Values for the AuxiliarySectionDefinition::selection attribute

See: https://learn.microsoft.com/en-us/windows/win32/debug/pe-format#comdat-sections-object-only

ANY = 2¶

ASSOCIATIVE = 5¶

EXACT_MATCH = 4¶

LARGEST = 6¶

NODUPLICATES = 1¶

NONE = 0¶

SAME_SIZE = 3¶

property checksum → int¶: The checksum for communal data. It is applicable if the IMAGE_SCN_LNK_COMDAT flag is set in the section header.

property length → int¶: The size of section data. The same as SizeOfRawData in the section header.

property nb_line_numbers → int¶: The number of line-number entries for the section.

property nb_relocs → int¶: The number of relocation entries for the section.

property reserved → int¶: Reserved value (should be 0)

property section_idx → int¶: One-based index into the section table for the associated section. This is used when the COMDAT selection setting is 5.

property selection → lief.COFF.AuxiliarySectionDefinition.COMDAT_SELECTION¶: The COMDAT selection number. This is applicable if the section is a COMDAT section.

AuxiliaryFile¶

class lief.COFF.AuxiliaryFile¶

Bases: AuxiliarySymbol

This auxiliary symbol represents a filename (auxiliary format 4)

The lief.Symbol.name itself should start with .file, and this auxiliary record gives the name of a source-code file.

Reference: https://learn.microsoft.com/en-us/windows/win32/debug/pe-format#auxiliary-format-4-files

property filename → str¶: The associated filename

Utilities¶

lief.is_coff(file: str | os.PathLike) → bool¶: Check if the given file is a COFF