pe-parse

The pe-parse library provides a minimal API (defined in parser-library/parse.h) for analyzing Windows Portable Executable (PE) files. Key capabilities include:

• Opening and closing PE files.
• Iterating over imported functions, relocations, exported functions, sections, and resources.
• Reading bytes from specified virtual addresses (as well as file offsets).
• Retrieving the program entry point.

Warning: The error handling in pe-parse is not thread safe. If performing parses or writes in multiple threads, you must synchronize operations independently.

To build the project using standard CMake instructions:

git clone https://github.com/trailofbits/pe-parse.git
cd pe-parse

mkdir build
cd build

cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build .

# Optional: Install to system
cmake --build . --target install

To use the pe-parse library in your own C++ project, use find_package and link against the pe-parse::pe-parse target.

find_package(pe-parse REQUIRED)

target_link_libraries(your_target_name PRIVATE pe-parse::pe-parse)

Use the following CMake commands depending on your Visual Studio version to ensure correct architecture (Win64):

• VS 2017: cmake -G "Visual Studio 15 2017 Win64" ..
• VS 2019: cmake -G "Visual Studio 16 2019" -A Win64 ..
• VS 2022: cmake -G "Visual Studio 17 2022" -A Win64 ..
• VS 2026: cmake -G "Visual Studio 18 2026" -A Win64 ..

To pass the build type at build time, use: cmake --build . --config Release

To build pepy from source, you must have pe-parse already built and a working Python environment with headers and libraries available.

Note for Windows users: Python is typically installed as python.exe, not python3.exe.

# 1. Build pepy
pip install build && python3 -m build

# 2. Install pepy
pip install .

Depending on your platform, you may need to install ICU and CMake.

ICU (Required on Linux and macOS; NOT required on Windows)

• Debian/Ubuntu: sudo apt-get install libicu-dev
• RedHat/Fedora: sudo dnf install libicu-devel
• macOS: brew install icu4c
• vcpkg: vcpkg install icu

CMake

• Debian/Ubuntu: sudo apt-get install cmake
• RedHat/Fedora: sudo apt-get install cmake (or yum)
• macOS: brew install cmake
• Windows: Download from cmake.org

Before building any examples (such as peaddrconv), you must first install the pe-parse library to your system. This is done using CMake after configuring the project.

cmake --build . --config Release --target install

When ICU is installed via Homebrew, you must set the ICU_ROOT environment variable to the specific installation path (e.g., /opt/homebrew/opt/icu4c@version) so CMake can locate it.

ICU_ROOT=/opt/homebrew/opt/icu4c@123 cmake -DCMAKE_BUILD_TYPE=Release ..
ICU_ROOT=/opt/homebrew/opt/icu4c@123 cmake --build .

By default, tests and examples are not built. You can enable them using CMake flags:

• Enable Tests: Add -DPEPARSE_ENABLE_TESTING=ON to your CMake configuration. Run tests using ctest or cmake --build . --target test.
• Enable Examples: Add -DPEPARSE_ENABLE_EXAMPLES=ON to your CMake configuration.

Note on Corkami test suite: To run the full test suite with the Corkami tests, you must first initialize the submodule: git submodule update --init.

The easiest way to install the pepy Python bindings is using pip.

$ pip3 install pepy

For development and testing, you can compile with C++ sanitizers by setting the PEPARSE_USE_SANITIZER flag. Supported sanitizers include: Address, HWAddress, Undefined, Memory, MemoryWithOrigins, Leak, and Address,Undefined.

Example using both Address and Undefined sanitizers:

mkdir build-san
cd build-san

cmake -DCMAKE_BUILD_TYPE=Debug -DPEPARSE_ENABLE_TESTING=ON -DPEPARSE_USE_SANITIZER=Address,Undefined ..
cmake --build .

You can install the C++ library using vcpkg or the Python bindings (pepy) using pip.

C++ Library:

vcpkg install pe-parse

Python Bindings (pepy):

pip3 install pepy