pefile

pefile is a multi-platform Python module to parse and work with Portable Executable (PE) files. Most of the information contained in the PE file headers is accessible, as well as all the sections' details and data.

The structures defined in the Windows header files will be accessible as attributes in the PE instance. The naming of fields/attributes will try to adhere to the naming scheme in those headers. Only shortcuts added for convenience will depart from that convention.

pefile requires some basic understanding of the layout of a PE file — with it, it is possible to explore nearly every single feature of the PE file format.

Installation

To install pefile through pip:

pip3 install pefile

source checkout

this repository contains a large compressed test corpus, and its git history retains older versions of that corpus. a full clone can therefore be much larger than the library itself. use the pip installation above if you only need the library.

to work on the source without downloading the test corpus or its history:

git clone --depth 1 --filter=blob:none --sparse https://github.com/erocarrera/pefile.git
cd pefile
git sparse-checkout set ordlookup

this checks out the library and its ordinal lookup tables. to include the tests, run git sparse-checkout set ordlookup tests; this also downloads the large test corpus. --depth 1 omits older history, and filtered clones fetch additional file contents when needed.

Features

Some of the tasks that pefile makes possible are:

• Inspecting headers
• Analyzing of sections' data
• Retrieving embedded data
• Reading strings from the resources
• Warnings for suspicious and malformed values
• Basic modifying of PEs, like writing to some fields and other parts of the PE
  • This functionality won't rearrange PE file structures to make room for new fields, so use it with care.
  • Overwriting fields should mostly be safe.
• Packer detection with PEiD’s signatures
• PEiD signature generation

Please, refer to Usage Examples for some code snippets that demonstrate how to use pefile.

Here are a few examples of what a dump produced with pefile looks like for different types of files:

• a packed file
• kernel32.dll
• TinyPE

To work with authenticated binaries, including Authenticode signatures, please check the project verify-sigs.

pefile runs in several pipelines scanning hundreds of thousands of new PE files every day, and, while not perfect, it has grown to be pretty robust over time. That being said, small glitches are found now and then. If you bump into a PE that does not appear to be processed correctly, do report it, please! It will help make pefile a tiny bit more powerful.

Dependencies

pefile is self-contained. The module has no dependencies; it is endianness independent; and it works on Windows, macOS, and Linux.

Running tests

The test runner lives in tests/pefile_test.py. Its PE samples and expected dumps come from the separate pefile-tests repository. Clone that repository into pefile-tests/ at the root of this checkout, then run:

python -m pip install -e ".[dev]"
python -m pytest tests

CI checks out the corpus in the same location and runs this test module through tox. The corpus remains in its own repository so binary samples and expected dumps can be updated independently.

Projects and products using pefile

• Didier Stevens' pecheck, a tool for displaying PE file info, handles PEiD files better then pefile does.
• MAEC, a standardized language for encoding and communicating high-fidelity information about malware based upon attributes such as behaviors, artifacts, and attack patterns. MAEC converts pefile's output into their XML format.
• Qiew, a Hex/File format viewer.
• VirusTotal
• bbfreeze
• pyemu: download, GitHub, whitepaper
• Immunity Debugger 1.1
• Cuckoo
• CAPE
• MultiScanner
• PE Tree
• icoextract

Additional resources

PDFs of posters depicting the PE file format:

• Portable Executable Format Layout shows the full view of the headers and structures defined by the PE format.
• Portable Executable Header Walkthrough shows the raw view of an executable file with the PE format fields laid out over the corresponding areas.

The following links provide detailed information about the PE format and its structures.